sneakoscope 4.4.0 → 4.6.0

package/dist/scripts/release-registry-check.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -27,7 +26,7 @@ function readJson(file) {
         return JSON.parse(fs.readFileSync(path.join(root, file), 'utf8'));
     }
     catch (err) {
-        fail(`unable to read ${file}`, err.message);
+        fail(`unable to read ${file}`, err instanceof Error ? err.message : String(err));
     }
 }
 function run(cmd, args, options = {}) {
@@ -58,17 +57,23 @@ function checkPackagePublishConfig(pkg) {
     if (isPrerelease && pkg.publishConfig?.tag !== 'rc') {
         fail('package.json publishConfig.tag must be rc for prerelease versions', `found: ${pkg.publishConfig?.tag || 'missing'}\nversion: ${pkg.version}`);
     }
-    if (!isPrerelease && pkg.publishConfig?.tag && pkg.publishConfig.tag !== 'latest') {
-        fail('package.json publishConfig.tag must be latest or omitted for stable versions', `found: ${pkg.publishConfig.tag}\nversion: ${pkg.version}`);
+    if (!isPrerelease && pkg.publishConfig?.tag && pkg.publishConfig.tag !== 'latest' && !isBackfillTag(pkg.publishConfig.tag)) {
+        fail('package.json publishConfig.tag must be latest, omitted, or explicit backfill-* for stable backfill versions', `found: ${pkg.publishConfig.tag}\nversion: ${pkg.version}`);
     }
 }
 function checkRootNpmrc(pkg) {
     const npmrcPath = path.join(root, '.npmrc');
-    if (!fs.existsSync(npmrcPath))
+    const publishConfigTag = String(pkg.publishConfig?.tag || '');
+    if (!fs.existsSync(npmrcPath)) {
+        if (isBackfillTag(publishConfigTag)) {
+            fail('root .npmrc must pin the backfill publish tag for npm publish --ignore-scripts', `expected: tag=${publishConfigTag}`);
+        }
         return;
+    }
     const text = fs.readFileSync(npmrcPath, 'utf8');
     const unsafe = [];
     const isPrerelease = /-/.test(String(pkg.version || ''));
+    let npmrcTag = '';
     for (const [index, line] of text.split(/\r?\n/).entries()) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith(';'))
@@ -78,16 +83,23 @@ function checkRootNpmrc(pkg) {
             unsafe.push(`${index + 1}: ${trimmed}`);
         const tagMatch = trimmed.match(/^tag\s*=\s*(.+)$/);
         if (tagMatch) {
-            const tag = tagMatch[1].trim();
+            const tag = String(tagMatch[1] || '').trim();
+            npmrcTag = tag;
             if (isPrerelease && tag !== 'rc')
                 unsafe.push(`${index + 1}: ${trimmed}`);
-            if (!isPrerelease && tag !== 'latest')
+            if (!isPrerelease && tag !== 'latest' && !isBackfillTag(tag))
                 unsafe.push(`${index + 1}: ${trimmed}`);
         }
     }
     if (unsafe.length) {
         fail('root .npmrc contains publish config incompatible with this release', unsafe.join('\n'));
     }
+    if (publishConfigTag && npmrcTag && publishConfigTag !== npmrcTag) {
+        fail('root .npmrc tag disagrees with package.json publishConfig.tag', `.npmrc tag: ${npmrcTag}\npublishConfig.tag: ${publishConfigTag}`);
+    }
+    if (isBackfillTag(publishConfigTag) && npmrcTag !== publishConfigTag) {
+        fail('root .npmrc must pin the backfill publish tag for npm publish --ignore-scripts', `.npmrc tag: ${npmrcTag || 'missing'}\nexpected: ${publishConfigTag}`);
+    }
 }
 function checkLockfile(pkg) {
     const lock = readJson('package-lock.json');
@@ -147,8 +159,10 @@ function compareVersions(a, b) {
     const pb = String(b || '').split(/[.-]/).map((part) => Number.parseInt(part, 10));
     const len = Math.max(pa.length, pb.length);
     for (let i = 0; i < len; i += 1) {
-        const da = Number.isFinite(pa[i]) ? pa[i] : 0;
-        const db = Number.isFinite(pb[i]) ? pb[i] : 0;
+        const paValue = pa[i];
+        const pbValue = pb[i];
+        const da = Number.isFinite(paValue) ? paValue || 0 : 0;
+        const db = Number.isFinite(pbValue) ? pbValue || 0 : 0;
         if (da !== db)
             return da > db ? 1 : -1;
     }
@@ -193,14 +207,17 @@ function checkPublishedVersion(pkg) {
         fail('package version is already published on npm', `${pkg.name}@${pkg.version}`);
     }
     const cmp = compareVersions(pkg.version, latest);
-    if (requireUnpublished && cmp <= 0) {
+    if (requireUnpublished && cmp <= 0 && !isBackfillTag(pkg.publishConfig?.tag || '')) {
         fail('package version is not newer than the npm latest dist-tag', `package.json: ${pkg.version}\nnpm latest: ${latest}`);
     }
     const note = exactPublished
         ? `exact version already exists; current npm latest is ${latest}`
-        : (cmp > 0 ? `ready for new publish over npm latest ${latest}` : `current npm latest is ${latest}`);
+        : (cmp > 0 ? `ready for new publish over npm latest ${latest}` : `ready as backfill over current npm latest ${latest} with tag ${pkg.publishConfig?.tag || 'missing'}`);
     console.log(`Registry metadata check passed: ${pkg.name}@${pkg.version}; ${note}.`);
 }
+function isBackfillTag(value) {
+    return /^backfill(?:[-_][a-z0-9.-]+)?$/i.test(String(value || ''));
+}
 function checkPublishAuth(pkg) {
     if (skipNetwork) {
         fail('publish auth check cannot run when SKS_SKIP_REGISTRY_NETWORK_CHECK=1 is set');
@@ -324,8 +341,10 @@ function packageMaintainers(pkg, env) {
 function normalizeNpmUser(value) {
     if (!value)
         return '';
-    if (typeof value === 'object')
-        return normalizeNpmUser(value.name || value.username || '');
+    if (typeof value === 'object') {
+        const record = value;
+        return normalizeNpmUser(record.name || record.username || '');
+    }
     const text = String(value).trim();
     if (/^["[{]/.test(text)) {
         try {
@@ -335,7 +354,7 @@ function normalizeNpmUser(value) {
             // Fall through for legacy plain-text npm output.
         }
     }
-    return text.replace(/^@/, '').split(/\s+/)[0].toLowerCase();
+    return String(text.replace(/^@/, '').split(/\s+/)[0] || '').toLowerCase();
 }
 function tail(value, limit = 1200) {
     const text = String(value || '').trim();

package/dist/scripts/search-visibility-gate-lib.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { assertGate, emitGate, root } from './sks-1-18-gate-lib.js';
+export { assertGate, emitGate, root };
+export function makeSearchVisibilityFixture(name = 'search-visibility', options = {}) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), `sks-${name}-`));
+    fs.mkdirSync(path.join(dir, 'public'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'bin'), { recursive: true });
+    const packageJson = {
+        name: `sks-${name}-fixture`,
+        version: '0.0.0',
+        description: options.description || 'Source-backed search visibility fixture for Sneakoscope gates.',
+        keywords: ['sneakoscope', 'search-visibility'],
+        repository: { type: 'git', url: 'https://example.test/repo.git' },
+        homepage: 'https://example.test/',
+        bugs: { url: 'https://example.test/issues' },
+        bin: { [`${name}-fixture`]: 'bin/fixture.js' },
+        scripts: { build: 'node -e "console.log(1)"' },
+    };
+    fs.writeFileSync(path.join(dir, 'package.json'), `${JSON.stringify(packageJson, null, 2)}\n`);
+    fs.writeFileSync(path.join(dir, 'bin', 'fixture.js'), '#!/usr/bin/env node\nconsole.log("fixture")\n');
+    fs.writeFileSync(path.join(dir, 'README.md'), `# ${options.title || 'Search Visibility Fixture'}\n\nInstall with \`npm i\` and run \`${name}-fixture\`.\n`);
+    fs.writeFileSync(path.join(dir, 'public', 'index.html'), options.html || [
+        '<!doctype html>',
+        '<html lang="en">',
+        '<head><meta charset="utf-8"><title>Search Visibility Fixture</title><meta name="description" content="A source-backed fixture."></head>',
+        '<body><main><h1>Search Visibility Fixture</h1><p>Official source-backed content.</p><a href="/docs">Docs</a></main></body>',
+        '</html>',
+        '',
+    ].join('\n'));
+    return dir;
+}
+export function runSks(args, options = {}) {
+    const result = spawnSync(process.execPath, [path.join(root, 'dist', 'bin', 'sks.js'), ...args], {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: 'pipe',
+        env: {
+            ...process.env,
+            SKS_REQUIRE_ZELLIJ: '0',
+            SKS_TEST_REAL_IMAGEGEN: '0',
+            SKS_REAL_IMAGEGEN: '0',
+            SKS_REQUIRE_REAL_COMPUTER_USE: '0',
+            ...(options.env || {}),
+        },
+        timeout: options.timeoutMs || 120000,
+    });
+    if (!options.allowFailure) {
+        assertGate(result.status === 0, `sks command failed: ${args.join(' ')}`, {
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        });
+    }
+    return result;
+}
+export function runSksJson(args, options = {}) {
+    const result = runSks(args, options);
+    const parsed = parseJsonOutput(result.stdout);
+    assertGate(parsed && typeof parsed === 'object', `sks command did not emit JSON: ${args.join(' ')}`, {
+        status: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    });
+    return { result, json: parsed };
+}
+export function parseJsonOutput(stdout) {
+    const text = String(stdout || '').trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch { }
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start >= 0 && end > start) {
+        try {
+            return JSON.parse(text.slice(start, end + 1));
+        }
+        catch { }
+    }
+    return null;
+}
+export function missionDir(missionId, baseRoot = root) {
+    return path.join(baseRoot, '.sneakoscope', 'missions', missionId);
+}
+export function artifactPath(missionId, rel, baseRoot = root) {
+    return path.join(missionDir(missionId, baseRoot), rel.startsWith('search-visibility/') ? rel : path.join('search-visibility', rel));
+}
+export function readJsonFile(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+export function assertMissionArtifact(missionId, rel, baseRoot = root) {
+    const file = rel === 'completion-proof.json' || rel.endsWith('-gate.json')
+        ? path.join(missionDir(missionId, baseRoot), rel)
+        : artifactPath(missionId, rel, baseRoot);
+    assertGate(fs.existsSync(file), `missing mission artifact: ${rel}`, { missionId, file });
+    return readJsonFile(file);
+}
+export function listSourceFiles(dir) {
+    const out = [];
+    walk(dir, out);
+    return out
+        .map((file) => path.relative(dir, file).split(path.sep).join('/'))
+        .filter((rel) => !rel.startsWith('.sneakoscope/'))
+        .sort();
+}
+function walk(dir, out) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.sneakoscope' || entry.name === 'node_modules' || entry.name === '.git')
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(full, out);
+        else if (entry.isFile())
+            out.push(full);
+    }
+}
+//# sourceMappingURL=search-visibility-gate-lib.js.map

package/dist/scripts/seo-audit-fixture-check.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { assertGate, assertMissionArtifact, emitGate, makeSearchVisibilityFixture, runSksJson } from './search-visibility-gate-lib.js';
+const fixture = makeSearchVisibilityFixture('seo-audit');
+const { json } = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'seo', '--root', fixture, '--target', 'website', '--framework', 'static', '--url', 'https://example.test', '--offline', '--json']);
+assertGate(json.route === '$SEO-GEO-OPTIMIZER' && json.mission_id, 'seo audit must create a unified optimizer mission', json);
+const inventory = assertMissionArtifact(json.mission_id, 'site-inventory.json', fixture);
+const findings = assertMissionArtifact(json.mission_id, 'seo-findings.json', fixture);
+const gate = assertMissionArtifact(json.mission_id, 'seo-gate.json', fixture);
+const proof = assertMissionArtifact(json.mission_id, 'completion-proof.json', fixture);
+assertGate(inventory.detected_adapter.adapterId === 'static-site', 'fixture should detect static-site adapter', inventory.detected_adapter);
+assertGate(Array.isArray(findings.findings) && findings.findings.every((finding) => finding.evidence?.length > 0), 'SEO findings must be atomic and evidence-backed', findings);
+assertGate(gate.route === '$SEO-GEO-OPTIMIZER' && gate.completion_proof.endsWith('/completion-proof.json'), 'seo gate must link completion proof', gate);
+assertGate(proof.schema === 'sks.completion-proof.v1' && proof.route === '$SEO-GEO-OPTIMIZER', 'completion proof must retain unified route identity', proof);
+emitGate('seo:audit-fixture', { mission_id: json.mission_id, findings: findings.findings.length });
+//# sourceMappingURL=seo-audit-fixture-check.js.map

package/dist/scripts/seo-canonical-locale-check.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertGate, assertMissionArtifact, emitGate, makeSearchVisibilityFixture, runSksJson } from './search-visibility-gate-lib.js';
+const fixture = makeSearchVisibilityFixture('seo-locale');
+fs.mkdirSync(path.join(fixture, 'public', 'fr'), { recursive: true });
+fs.writeFileSync(path.join(fixture, 'public', 'fr', 'index.html'), '<!doctype html><html lang="fr"><head><title>FR</title><link rel="canonical" href="/fr"></head><body><h1>FR</h1></body></html>\n');
+const audit = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'seo', '--root', fixture, '--target', 'website', '--framework', 'static', '--url', 'https://example.test', '--offline', '--json']).json;
+const canonical = assertMissionArtifact(audit.mission_id, 'canonical-map.json', fixture);
+const locale = assertMissionArtifact(audit.mission_id, 'locale-graph.json', fixture);
+const sitemap = assertMissionArtifact(audit.mission_id, 'sitemap-audit.json', fixture);
+const findings = assertMissionArtifact(audit.mission_id, 'seo-findings.json', fixture);
+assertGate(/not guaranteed/i.test(canonical.warning), 'canonical report must avoid search-engine selection guarantees', canonical);
+assertGate(locale.checks.self_hreflang_verified === false && Array.isArray(locale.unverified), 'locale report must separate unverified hreflang checks', locale);
+assertGate(sitemap.indexing_guarantee === false, 'sitemap report must not claim indexing guarantee', sitemap);
+assertGate(findings.findings.some((finding) => finding.ruleId.includes('canonical') || finding.category === 'locale'), 'fixture should produce canonical or locale findings', findings);
+emitGate('seo:canonical-sitemap-locale', { mission_id: audit.mission_id });
+//# sourceMappingURL=seo-canonical-locale-check.js.map

package/dist/scripts/seo-cli-blackbox-check.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { assertGate, emitGate, runSks, runSksJson } from './search-visibility-gate-lib.js';
+const commands = runSksJson(['commands', '--json']).json;
+assertGate(commands.commands.some((row) => row.name === 'seo-geo-optimizer' && /unified SEO\/GEO optimizer/i.test(row.description)), 'commands --json must expose seo-geo-optimizer');
+assertGate(!commands.commands.some((row) => row.name === 'seo' || row.name === 'geo'), 'commands --json must not expose split seo/geo command surfaces');
+const optimizerUsage = runSks(['usage', 'seo-geo-optimizer']);
+assertGate(/sks seo-geo-optimizer \[seo\|geo\] doctor\|audit\|plan\|apply\|verify\|status\|rollback\|fixture/.test(optimizerUsage.stdout), 'usage seo-geo-optimizer must expose unified lifecycle');
+const doctor = runSksJson(['seo-geo-optimizer', 'doctor', '--mode', 'seo', '--json']).json;
+assertGate(doctor.route === '$SEO-GEO-OPTIMIZER' && doctor.schema === 'sks.search-visibility.doctor-command.v1', 'optimizer seo doctor must preserve unified route identity', doctor);
+const invalid = runSks(['seo-geo-optimizer', 'nonsense-subcommand'], { allowFailure: true });
+assertGate(invalid.status === 2 && /Usage: sks seo-geo-optimizer/.test(invalid.stderr), 'invalid optimizer subcommand must exit 2 with usage', {
+    status: invalid.status,
+    stdout: invalid.stdout,
+    stderr: invalid.stderr,
+});
+emitGate('seo:cli-blackbox', { adapter: doctor.adapter, confidence: doctor.confidence });
+//# sourceMappingURL=seo-cli-blackbox-check.js.map

package/dist/scripts/seo-geo-feature-fixture-quality-check.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { assertGate, emitGate, importDist, root } from './sks-1-18-gate-lib.js';
+const registryMod = await importDist('core/feature-registry.js');
+const registry = await registryMod.buildFeatureRegistry({ root });
+const byId = new Map(registry.features.map((feature) => [feature.id, feature]));
+for (const id of ['cli-seo-geo-optimizer', 'route-seo-geo-optimizer']) {
+    const feature = byId.get(id);
+    assertGate(feature, `feature missing: ${id}`);
+    assertGate(feature.fixture?.status === 'pass', `feature fixture must pass: ${id}`, feature);
+    assertGate(feature.fixture?.quality !== 'static_contract', `SEO/GEO feature must not rely on static contract: ${id}`, feature.fixture);
+    assertGate(['runtime_verified', 'runtime_mock_verified'].includes(feature.fixture?.quality), `SEO/GEO fixture quality must be runtime-backed: ${id}`, feature.fixture);
+}
+const selftest = registryMod.buildAllFeaturesSelftest(registry, {});
+const runtimeCheck = selftest.checks.find((check) => check.id === 'runtime_routes_not_static_contract');
+assertGate(runtimeCheck?.ok === true, 'runtime route static-contract guard must pass', runtimeCheck);
+emitGate('seo-geo:feature-fixture-quality', { features: 2 });
+//# sourceMappingURL=seo-geo-feature-fixture-quality-check.js.map

package/dist/scripts/seo-geo-geo-disambiguation-check.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { assertGate, emitGate, importDist } from './sks-1-18-gate-lib.js';
+const routes = await importDist('core/routes.js');
+const commandFor = (prompt) => routes.routePrompt(prompt)?.command;
+assertGate(commandFor('$SEO-GEO-OPTIMIZER improve AI answer visibility') === '$SEO-GEO-OPTIMIZER', 'explicit optimizer should route to unified route');
+assertGate(commandFor('Generative Engine Optimization crawler policy audit') === '$SEO-GEO-OPTIMIZER', 'generative engine optimization should route to unified optimizer');
+assertGate(commandFor('SEO audit canonical sitemap metadata') === '$SEO-GEO-OPTIMIZER', 'SEO intent should route to unified optimizer');
+assertGate(commandFor('fix GeoIP regional redirect bug') !== '$SEO-GEO-OPTIMIZER', 'GeoIP/geolocation request must not route to optimizer');
+assertGate(commandFor('map coordinates and location permission issue') !== '$SEO-GEO-OPTIMIZER', 'location permission request must not route to optimizer');
+emitGate('seo-geo:geo-disambiguation');
+//# sourceMappingURL=seo-geo-geo-disambiguation-check.js.map

package/dist/scripts/seo-geo-no-unsupported-ranking-claims-check.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertGate, assertMissionArtifact, emitGate, makeSearchVisibilityFixture, runSksJson } from './search-visibility-gate-lib.js';
+const fixture = makeSearchVisibilityFixture('unsupported-claims', {
+    description: 'Guarantees top rank and AI citation for every site.',
+});
+fs.appendFileSync(path.join(fixture, 'README.md'), '\nWe guarantee rank #1, traffic lift, and AI answer citation.\n');
+const seo = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'seo', '--root', fixture, '--target', 'package', '--offline', '--json'], { allowFailure: true }).json;
+const geo = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'geo', '--root', fixture, '--target', 'package', '--offline', '--json'], { allowFailure: true }).json;
+const seoGate = assertMissionArtifact(seo.mission_id, 'seo-gate.json', fixture);
+const geoGate = assertMissionArtifact(geo.mission_id, 'geo-gate.json', fixture);
+const claims = assertMissionArtifact(geo.mission_id, 'claim-evidence-ledger.json', fixture);
+assertGate(seoGate.ok === false && seoGate.unsupported_claims.length > 0, 'SEO gate must reject unsupported ranking/traffic/citation guarantees', seoGate);
+assertGate(geoGate.ok === false && claims.claims.some((claim) => claim.safe_to_publish === false), 'GEO gate must reject unsupported AI citation claims', { geoGate, claims });
+emitGate('seo-geo:no-unsupported-ranking-claims', { seo_mission: seo.mission_id, geo_mission: geo.mission_id });
+//# sourceMappingURL=seo-geo-no-unsupported-ranking-claims-check.js.map

package/dist/scripts/seo-geo-route-identity-check.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { assertGate, emitGate, runSksJson } from './search-visibility-gate-lib.js';
+const seo = runSksJson(['run', '$SEO-GEO-OPTIMIZER SEO audit this fixture', '--execute', '--json']).json;
+const geo = runSksJson(['run', '$SEO-GEO-OPTIMIZER Generative Engine Optimization audit AI search visibility', '--execute', '--json']).json;
+const seoText = JSON.stringify(seo);
+const geoText = JSON.stringify(geo);
+assertGate(/\$SEO-GEO-OPTIMIZER/.test(seoText) && /sks seo-geo-optimizer/.test(seoText) && /--mode seo/.test(seoText), 'sks run --execute must preserve unified optimizer route and execute seo mode path', seo);
+assertGate(/\$SEO-GEO-OPTIMIZER/.test(geoText) && /sks seo-geo-optimizer/.test(geoText) && /--mode geo/.test(geoText), 'sks run --execute must preserve unified optimizer route and execute geo mode path', geo);
+assertGate(!/\$AutoResearch/.test(seoText) && !/\$AutoResearch/.test(geoText), 'SEO/GEO route identity must not collapse into AutoResearch', { seo, geo });
+emitGate('seo-geo:route-identity', { seo_status: seo.status, geo_status: geo.status });
+//# sourceMappingURL=seo-geo-route-identity-check.js.map

package/dist/scripts/seo-geo-skill-rich-content-check.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { assertGate, emitGate, importDist } from './sks-1-18-gate-lib.js';
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'sks-seo-geo-skills-'));
+const init = await importDist('core/init.js');
+await init.installSkills(root);
+for (const name of ['search-visibility-core', 'seo-geo-optimizer']) {
+    const file = path.join(root, '.agents', 'skills', name, 'SKILL.md');
+    assertGate(fs.existsSync(file), `generated skill missing: ${name}`);
+    const text = fs.readFileSync(file, 'utf8');
+    assertGate(/^---\nname:/m.test(text) && /description:/.test(text), `skill frontmatter missing: ${name}`, text);
+    for (const token of ['Purpose:', 'Use when', 'Workflow:', 'Safety:', 'Evidence/artifacts:', 'Failure/recovery:']) {
+        assertGate(text.includes(token), `skill missing rich token ${token}: ${name}`, text);
+    }
+    assertGate(/CLI entrypoint:/i.test(text), `skill missing CLI entrypoint: ${name}`, text);
+    assertGate(/ranking|citation|traffic|guarantee|보장/i.test(text), `skill must name forbidden guarantee boundary: ${name}`, text);
+}
+emitGate('seo-geo:skill-rich-content', { skills_checked: 2 });
+//# sourceMappingURL=seo-geo-skill-rich-content-check.js.map

package/dist/scripts/seo-mutation-rollback-check.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertGate, assertMissionArtifact, emitGate, makeSearchVisibilityFixture, runSksJson } from './search-visibility-gate-lib.js';
+const fixture = makeSearchVisibilityFixture('seo-rollback');
+const audit = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'seo', '--root', fixture, '--target', 'website', '--framework', 'static', '--url', 'https://example.test', '--offline', '--json']).json;
+const plan = runSksJson(['seo-geo-optimizer', 'plan', audit.mission_id, '--mode', 'seo', '--root', fixture, '--json']).json;
+assertGate(plan.operations >= 2, 'SEO rollback fixture should plan robots and sitemap creation', plan);
+const apply = runSksJson(['seo-geo-optimizer', 'apply', audit.mission_id, '--mode', 'seo', '--root', fixture, '--apply', '--json']).json;
+assertGate(apply.ok === true && apply.applied >= 2, 'SEO apply must create planned managed files', apply);
+assertGate(fs.existsSync(path.join(fixture, 'public', 'robots.txt')) && fs.existsSync(path.join(fixture, 'public', 'sitemap.xml')), 'managed robots and sitemap must exist after apply');
+const second = runSksJson(['seo-geo-optimizer', 'apply', audit.mission_id, '--mode', 'seo', '--root', fixture, '--apply', '--json']).json;
+assertGate(second.ok === true, 'second apply must be idempotent', second);
+const journal = fs.readFileSync(path.join(fixture, '.sneakoscope', 'missions', audit.mission_id, 'search-visibility', 'mutation-journal.jsonl'), 'utf8');
+assertGate(/applied/.test(journal), 'mutation journal must record applied/idempotent events', journal);
+const rollbackManifest = assertMissionArtifact(audit.mission_id, 'rollback-manifest.json', fixture);
+assertGate(rollbackManifest.operations.length >= 2, 'rollback manifest must preserve inverse operations after idempotent apply', rollbackManifest);
+const rollback = runSksJson(['seo-geo-optimizer', 'rollback', audit.mission_id, '--mode', 'seo', '--root', fixture, '--apply', '--json']).json;
+assertGate(rollback.ok === true && rollback.rolled_back >= 2, 'rollback must reverse mission-owned operations', rollback);
+assertGate(!fs.existsSync(path.join(fixture, 'public', 'robots.txt')) && !fs.existsSync(path.join(fixture, 'public', 'sitemap.xml')), 'rollback must remove mission-created files');
+emitGate('seo:mutation-rollback', { mission_id: audit.mission_id, applied: apply.applied, rolled_back: rollback.rolled_back });
+//# sourceMappingURL=seo-mutation-rollback-check.js.map

package/dist/scripts/seo-no-mutation-by-default-check.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertGate, emitGate, listSourceFiles, makeSearchVisibilityFixture, runSksJson } from './search-visibility-gate-lib.js';
+const fixture = makeSearchVisibilityFixture('seo-readonly');
+const before = listSourceFiles(fixture);
+const audit = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'seo', '--root', fixture, '--target', 'website', '--framework', 'static', '--url', 'https://example.test', '--offline', '--json']).json;
+const plan = runSksJson(['seo-geo-optimizer', 'plan', audit.mission_id, '--mode', 'seo', '--root', fixture, '--json']).json;
+const blockedApply = runSksJson(['seo-geo-optimizer', 'apply', audit.mission_id, '--mode', 'seo', '--root', fixture, '--json'], { allowFailure: true }).json;
+const after = listSourceFiles(fixture);
+assertGate(JSON.stringify(before) === JSON.stringify(after), 'audit/plan/apply-without-flag must not mutate project source files', { before, after });
+assertGate(plan.operations > 0, 'readonly fixture should still compile a mutation plan', plan);
+assertGate(blockedApply.ok === false && blockedApply.blockers.includes('apply_requires_explicit_--apply'), 'apply must require explicit --apply', blockedApply);
+assertGate(!fs.existsSync(path.join(fixture, 'public', 'robots.txt')) && !fs.existsSync(path.join(fixture, 'public', 'sitemap.xml')), 'policy files must not be created without --apply');
+emitGate('seo:no-mutation-by-default', { mission_id: audit.mission_id, planned_operations: plan.operations });
+//# sourceMappingURL=seo-no-mutation-by-default-check.js.map

package/dist/scripts/seo-structured-data-visible-content-check.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { assertGate, assertMissionArtifact, emitGate, makeSearchVisibilityFixture, runSksJson } from './search-visibility-gate-lib.js';
+const html = [
+    '<!doctype html>',
+    '<html lang="en"><head><title>Structured Data Fixture</title>',
+    '<script type="application/ld+json">{"@context":"https://schema.org","@type":"Product","aggregateRating":{"ratingValue":5,}}</script>',
+    '</head><body><h1>Structured Data Fixture</h1><p>Visible source content only.</p></body></html>',
+    '',
+].join('\n');
+const fixture = makeSearchVisibilityFixture('seo-structured', { html });
+const audit = runSksJson(['seo-geo-optimizer', 'audit', '--mode', 'seo', '--root', fixture, '--target', 'website', '--framework', 'static', '--url', 'https://example.test', '--offline', '--json']).json;
+const ledger = assertMissionArtifact(audit.mission_id, 'structured-data-ledger.json', fixture);
+const findings = assertMissionArtifact(audit.mission_id, 'seo-findings.json', fixture);
+assertGate(ledger.policies.some((url) => /structured-data/.test(url)), 'structured data ledger must cite structured-data policy sources', ledger);
+assertGate(ledger.pages.some((page) => page.parse_errors.length > 0), 'invalid JSON-LD must be recorded as parse error', ledger);
+assertGate(findings.findings.some((finding) => finding.ruleId.includes('jsonld-parse') && finding.evidence.length > 0), 'invalid JSON-LD finding must carry evidence', findings);
+emitGate('seo:structured-data-visible-content', { mission_id: audit.mission_id });
+//# sourceMappingURL=seo-structured-data-visible-content-check.js.map

package/dist/scripts/sks-3-1-5-directive-check-lib.js

@@ -251,7 +251,16 @@ async function richContentGate(id) {
         const report = await mod.syncCodexSksSkills({ root: rootDir, skillsRoot, apply: true });
         const skill = fs.readFileSync(path.join(skillsRoot, 'loop', 'SKILL.md'), 'utf8');
         assertGate(/Purpose:|Evidence:|Fallback:/.test(skill), 'managed skill must include rich route content', { skill, report });
-        return emitGate(id, { skills: report.created.length });
+        for (const name of ['search-visibility-core', 'seo-geo-optimizer']) {
+            const file = path.join(skillsRoot, name, 'SKILL.md');
+            assertGate(fs.existsSync(file), `managed skill missing: ${name}`, { report });
+            const text = fs.readFileSync(file, 'utf8');
+            assertGate(/Purpose:|Use when:|Workflow:|Safety:|Evidence\/artifacts:|Failure\/recovery:|CLI entrypoint:/i.test(text), `managed skill lacks rich content: ${name}`, { text });
+            assertGate(/ranking|citation|traffic|guarantee|보장/i.test(text), `managed skill must name forbidden guarantee boundary: ${name}`, { text });
+            if (name === 'seo-geo-optimizer')
+                assertGate(text.includes('sks seo-geo-optimizer doctor|audit|plan|apply|verify|status|rollback|fixture') && /not geolocation|GeoIP/i.test(text), 'seo-geo-optimizer skill must expose CLI entrypoint and geolocation disambiguation', { text });
+        }
+        return emitGate(id, { skills: report.created.length, search_visibility_skills_checked: 2 });
     }
     const previous = swapEnv({ SKS_CODEX_AGENT_TYPE_FIXTURE: 'supported' });
     try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "Sneakoscope Codex: fast proof-first Codex trust layer with image-based Voxel TriWiki.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -68,6 +68,21 @@
     "typescript:migration-report": "node ./dist/scripts/typescript-migration-report.js",
     "typecheck:contracts": "node ./dist/scripts/check-ts-contracts.js",
     "schema:check": "node ./dist/scripts/check-runtime-schemas.js",
+    "seo:cli-blackbox": "node ./dist/scripts/seo-cli-blackbox-check.js",
+    "seo:audit-fixture": "node ./dist/scripts/seo-audit-fixture-check.js",
+    "seo:no-mutation-by-default": "node ./dist/scripts/seo-no-mutation-by-default-check.js",
+    "seo:mutation-rollback": "node ./dist/scripts/seo-mutation-rollback-check.js",
+    "seo:canonical-sitemap-locale": "node ./dist/scripts/seo-canonical-locale-check.js",
+    "seo:structured-data-visible-content": "node ./dist/scripts/seo-structured-data-visible-content-check.js",
+    "geo:cli-blackbox": "node ./dist/scripts/geo-cli-blackbox-check.js",
+    "geo:claim-evidence": "node ./dist/scripts/geo-claim-evidence-check.js",
+    "geo:crawler-purpose-policy": "node ./dist/scripts/geo-crawler-policy-check.js",
+    "geo:llms-txt-optional": "node ./dist/scripts/geo-llms-txt-optional-check.js",
+    "seo-geo:route-identity": "node ./dist/scripts/seo-geo-route-identity-check.js",
+    "seo-geo:geo-disambiguation": "node ./dist/scripts/seo-geo-geo-disambiguation-check.js",
+    "seo-geo:skill-rich-content": "node ./dist/scripts/seo-geo-skill-rich-content-check.js",
+    "seo-geo:no-unsupported-ranking-claims": "node ./dist/scripts/seo-geo-no-unsupported-ranking-claims-check.js",
+    "seo-geo:feature-fixture-quality": "node ./dist/scripts/seo-geo-feature-fixture-quality-check.js",
     "package-boundary:check": "node ./dist/scripts/check-package-boundary.js",
     "blackbox:command-import-smoke": "node ./dist/scripts/blackbox-command-import-smoke.js",
     "repo-audit": "node ./dist/scripts/repo-audit.js",
@@ -1082,6 +1097,9 @@
     "goal",
     "research",
     "autoresearch",
+    "seo",
+    "search-visibility",
+    "generative-engine-optimization",
     "honest-mode",
     "update-check",
     "llm-wiki",

package/schemas/search-visibility/finding-ledger.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sneakoscope.dev/schemas/search-visibility/finding-ledger.schema.json",
+  "title": "SKS Search Visibility Finding Ledger",
+  "type": "object",
+  "required": ["schema", "mission_id", "route", "findings", "counts"],
+  "properties": {
+    "schema": { "enum": ["sks.search-visibility.seo-findings.v1", "sks.search-visibility.geo-findings.v1"] },
+    "mission_id": { "type": "string" },
+    "route": { "const": "$SEO-GEO-OPTIMIZER" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "ruleId", "domain", "category", "severity", "confidence", "blocking", "summary", "evidence", "affected", "remediation", "autoFixable"],
+        "properties": {
+          "id": { "type": "string" },
+          "ruleId": { "type": "string" },
+          "domain": { "enum": ["seo", "geo", "shared"] },
+          "category": { "type": "string" },
+          "severity": { "enum": ["info", "low", "medium", "high", "critical"] },
+          "confidence": { "type": "number" },
+          "blocking": { "type": "boolean" },
+          "summary": { "type": "string" },
+          "evidence": { "type": "array", "minItems": 1 },
+          "affected": { "type": "array" },
+          "remediation": { "type": "string" },
+          "autoFixable": { "type": "boolean" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "counts": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/schemas/search-visibility/gate.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sneakoscope.dev/schemas/search-visibility/gate.schema.json",
+  "title": "SKS Search Visibility Gate",
+  "type": "object",
+  "required": ["schema", "mission_id", "route", "ok", "passed", "status", "command_identity", "required_artifacts", "unsupported_claims", "blockers", "unverified", "completion_proof"],
+  "properties": {
+    "schema": { "const": "sks.search-visibility.gate.v1" },
+    "mission_id": { "type": "string" },
+    "route": { "const": "$SEO-GEO-OPTIMIZER" },
+    "ok": { "type": "boolean" },
+    "passed": { "type": "boolean" },
+    "status": { "enum": ["verified_partial", "blocked", "locally_verified", "production_verified"] },
+    "command_identity": { "type": "boolean" },
+    "required_artifacts": { "type": "array" },
+    "unsupported_claims": { "type": "array" },
+    "blockers": { "type": "array" },
+    "unverified": { "type": "array" },
+    "completion_proof": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/schemas/search-visibility/mutation-plan.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sneakoscope.dev/schemas/search-visibility/mutation-plan.schema.json",
+  "title": "SKS Search Visibility Mutation Plan",
+  "type": "object",
+  "required": ["schema", "mission_id", "route", "mode", "adapter", "detection_confidence", "status", "operations", "blockers", "unverified"],
+  "properties": {
+    "schema": { "const": "sks.search-visibility.mutation-plan.v1" },
+    "mission_id": { "type": "string" },
+    "route": { "const": "$SEO-GEO-OPTIMIZER" },
+    "mode": { "enum": ["seo", "geo"] },
+    "adapter": { "type": "string" },
+    "detection_confidence": { "type": "number" },
+    "status": { "enum": ["planned", "blocked"] },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "path", "baseSha256", "proposedSha256", "kind", "owner", "findingIds", "reversible", "preview", "risk", "requiredVerification", "scopeAuthorization", "ownershipStrategy"],
+        "additionalProperties": true
+      }
+    },
+    "blockers": { "type": "array" },
+    "unverified": { "type": "array" }
+  },
+  "additionalProperties": true
+}