sneakoscope 4.4.0 → 4.6.0

package/dist/core/routes.js

@@ -1,5 +1,7 @@
 import { PRODUCT_DESIGN_LEGACY_DESIGN_FALLBACK_SKILLS, PRODUCT_DESIGN_PLUGIN, PRODUCT_DESIGN_REQUIRED_SKILLS, productDesignPluginPolicyText } from './product-design-plugin.js';
+import { leanEngineeringCompactText, leanEngineeringLongText } from './lean-engineering-policy.js';
 export { productDesignPluginPolicyText };
+export { leanEngineeringCompactText, leanEngineeringLongText };
 const REFLECTION_SKILL_NAME = 'reflection';
 export const SOLUTION_SCOUT_SKILL_NAME = 'solution-scout';
 export const SOLUTION_SCOUT_STAGE_ID = 'solution_scout';
@@ -30,7 +32,7 @@ export const FROM_CHAT_IMG_CHECKLIST_ARTIFACT = 'from-chat-img-checklist.md';
 export const FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT = 'from-chat-img-temp-triwiki.json';
 export const FROM_CHAT_IMG_QA_LOOP_ARTIFACT = 'from-chat-img-qa-loop.json';
 export const FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS = 5;
-export const USAGE_TOPICS = 'install|setup|bootstrap|root|deps|zellij|tmux|auto-review|team|qa-loop|ppt|image-ux-review|computer-use|goal|fast-mode|research|db|git|codex|codex-app|codex-native|hooks|features|all-features|dfix|commit|commit-and-push|design|imagegen|dollar|context7|ultra-search|xai|pipeline|reasoning|guard|conflicts|versioning|eval|harness|hproof|gx|wiki|wrongness|code-structure|proof-field|skill-dream|rust';
+export const USAGE_TOPICS = 'install|setup|bootstrap|root|deps|zellij|tmux|auto-review|team|qa-loop|ppt|image-ux-review|computer-use|goal|fast-mode|research|seo-geo-optimizer|db|git|codex|codex-app|codex-native|hooks|features|all-features|dfix|commit|commit-and-push|design|imagegen|dollar|context7|ultra-search|xai|pipeline|reasoning|guard|conflicts|versioning|eval|harness|hproof|gx|wiki|wrongness|code-structure|proof-field|skill-dream|rust';
 export const CODEX_COMPUTER_USE_EVIDENCE_SOURCE = 'codex_computer_use';
 export const CODEX_IN_APP_BROWSER_EVIDENCE_SOURCE = 'codex_in_app_browser';
 export const CODEX_CHROME_EXTENSION_EVIDENCE_SOURCE = 'codex_chrome_extension';
@@ -181,6 +183,8 @@ export const RECOMMENDED_SKILLS = [
     'pipeline-runner',
     'solution-scout',
     'context7-docs',
+    'ultra-search',
+    'search-visibility-core',
     'seo-geo-optimizer',
     'autoresearch-loop',
     'performance-evaluator',
@@ -277,13 +281,13 @@ export function chatCaptureIntakeText() {
     return `From-Chat-IMG intake: explicit signal only. Select forensic visual effort. Treat uploads as chat screenshot plus originals. For web/browser/webapp targets, use the Codex Chrome Extension path first; for native Mac/non-web app surfaces, use Codex Computer Use visual inspection when available. List requirements first in source order, match regions to attachments with confidence, and write ${FROM_CHAT_IMG_WORK_ORDER_ARTIFACT}, ${FROM_CHAT_IMG_SOURCE_INVENTORY_ARTIFACT}, ${FROM_CHAT_IMG_VISUAL_MAP_ARTIFACT}, ${FROM_CHAT_IMG_COVERAGE_ARTIFACT}, ${FROM_CHAT_IMG_CHECKLIST_ARTIFACT}, ${FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT}, and ${FROM_CHAT_IMG_QA_LOOP_ARTIFACT}. ${CODEX_WEB_VERIFICATION_POLICY} ${CODEX_COMPUTER_USE_ONLY_POLICY} Preserve each visible customer request as source-bound text, account for every screenshot image region and separate attachment, map each item to work-order actions, perform the customer-request work, then run a scoped QA-LOOP over that exact work-order range before Team completion. Update checklist checkboxes as work proceeds until all boxes are checked, unresolved_items is empty, scoped_qa_loop_completed=true, QA unresolved findings are zero, and schema validation passes. ${FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT} is temporary TriWiki-backed session context with expires_after_sessions=${FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS}, so it can be forgotten by retention after enough later sessions. Do not assume ordinary image prompts are chat captures.`;
 }
 export function noUnrequestedFallbackCodePolicyText() {
-    return 'No unrequested fallback implementation code: every pipeline stage, executor, reviewer, auto-review profile, and MAD/MAD-SKS invocation must implement only the requested contract. Do not invent alternate code paths, substitute features, compatibility shims, mock behavior, or hidden fallbacks unless the user explicitly requested them or the sealed decision contract names them; if the requested path is impossible, block with evidence instead.';
+    return leanEngineeringCompactText();
 }
 export function outcomeRubricPolicyText() {
-    return 'Outcome rubric policy: before adding pipeline stages, use the existing Proof Field, route gate, reflection, and Honest Mode evidence as a compact rubric: goal fit, minimum touched surface, bounded verification, and explicit escalation triggers. Apply Hyperplan-derived adversarial lenses inside that rubric: challenge framing, subtract surface, demand evidence, test integration risk, and consider one simpler alternative. Prefer deleting or skipping unrelated work with evidence over adding a background loop; only add a new mechanism when it reduces net route weight or closes a proven gate gap.';
+    return 'Outcome rubric policy: use the Lean Engineering Policy plus existing Proof Field, route gate, reflection, and Honest Mode evidence as the compact rubric: goal fit, minimum touched surface, bounded verification, and explicit escalation triggers.';
 }
 export function speedLanePolicyText() {
-    return 'Proof Field speed lane policy: after the intended write scope is known, run or mentally apply `sks proof-field scan --intent "<goal>" --changed <files>`. If `execution_lane.lane` is `proof_field_fast_lane`, keep the parent-owned minimal patch, listed verification, TriWiki validate, and Honest Mode while skipping Team debate, fresh executor teams, broad route rework, and unrelated checks. If blockers include database, security, visual-forensic, unknown surface, broad change set, failed verification, or unsupported claims, fail closed to the normal Team/Honest path.';
+    return 'Proof Field speed lane policy: after the intended write scope is known, run or mentally apply `sks proof-field scan --intent "<goal>" --changed <files>`. Fast lanes keep the parent-owned minimal patch, listed verification, TriWiki validate, and Honest Mode; DB, security, visual-forensic, unknown surface, broad changes, failed verification, or unsupported claims fail closed to the normal Team/Honest path.';
 }
 export function hasFromChatImgSignal(prompt = '') {
     return /(?:^|\s)\$?from-chat-img(?:\s|:|$)/i.test(String(prompt || ''));
@@ -536,13 +540,42 @@ export const ROUTES = [
         cliEntrypoint: 'sks research prepare|run',
         examples: ['$Research investigate this idea']
     },
+    {
+        id: 'UltraSearch',
+        command: '$Ultra-Search',
+        mode: 'ULTRA_SEARCH',
+        route: 'provider-independent source intelligence',
+        description: 'Run UltraSearch source acquisition, source normalization, claim/proof ledgers, and provider-independent citation evidence without requiring xAI/Grok.',
+        requiredSkills: ['ultra-search', 'pipeline-runner', 'context7-docs', 'honest-mode'],
+        dollarAliases: ['$UltraSearch'],
+        lifecycle: ['source_intent', 'query_variants', 'provider_plan', 'source_ledgers', 'claim_ledgers', 'ultra_search_gate', 'honest_mode'],
+        context7Policy: 'if_external_docs',
+        reasoningPolicy: 'high',
+        stopGate: 'ultra-search/ultra-search-gate.json',
+        cliEntrypoint: 'sks ultra-search doctor|run|x|fetch|status|inspect|sources|claims|cache|bench|migrate-xai',
+        examples: ['$Ultra-Search run "current package release notes"', '$UltraSearch x "site:x.com product launch"']
+    },
+    {
+        id: 'SEOGEOOptimizer',
+        command: '$SEO-GEO-OPTIMIZER',
+        mode: 'SEO_GEO_OPTIMIZER',
+        route: 'search visibility optimization audit/apply/verify',
+        description: 'Unified SEO/GEO optimizer route for Search Engine Optimization and Generative Engine Optimization. Uses one shared kernel with mode-specific evidence, gates, safe apply, rollback, and Completion Proof. Not a ranking, traffic, or AI citation guarantee.',
+        requiredSkills: ['seo-geo-optimizer', 'search-visibility-core', 'pipeline-runner', REFLECTION_SKILL_NAME, 'honest-mode'],
+        lifecycle: ['doctor', 'read_only_audit', 'mode_specific_evidence', 'mutation_plan', 'explicit_apply_only', 'rollback_manifest', 'source_verify', 'seo_or_geo_gate', 'completion_proof', 'honest_mode'],
+        context7Policy: 'if_external_docs',
+        reasoningPolicy: 'high',
+        stopGate: 'seo-gate.json|geo-gate.json',
+        cliEntrypoint: 'sks seo-geo-optimizer doctor|audit|plan|apply|verify|status|rollback|fixture --mode seo|geo',
+        examples: ['$SEO-GEO-OPTIMIZER audit this site', 'sks seo-geo-optimizer audit --mode seo --target package --json', 'sks seo-geo-optimizer apply latest --mode geo --include-llms-txt --apply']
+    },
     {
         id: 'AutoResearch',
         command: '$AutoResearch',
         mode: 'AUTORESEARCH',
         route: 'iterative experiment loop',
         description: 'Program, hypothesize, test, measure, keep/discard, falsify, and report evidence.',
-        requiredSkills: ['autoresearch', 'autoresearch-loop', 'seo-geo-optimizer', 'performance-evaluator', 'pipeline-runner', 'context7-docs', REFLECTION_SKILL_NAME, 'honest-mode'],
+        requiredSkills: ['autoresearch', 'autoresearch-loop', 'performance-evaluator', 'pipeline-runner', 'context7-docs', REFLECTION_SKILL_NAME, 'honest-mode'],
         lifecycle: ['experiment_ledger', 'metric', 'keep_or_discard', 'falsification', 'post_route_reflection', 'honest_conclusion'],
         context7Policy: 'required',
         reasoningPolicy: 'xhigh',
@@ -674,7 +707,7 @@ export const COMMAND_CATALOG = [
     { name: 'hooks', usage: 'sks hooks explain|status|trust-report|replay|codex-validate|warning-check ... [--json]', description: 'Explain Codex hook events, validate vendored latest 10-event output schemas, replay fixtures, and enforce warning-zero SKS hook policies under the 0.134 compatibility matrix.' },
     { name: 'codex-lb', usage: 'sks codex-lb status|health|metrics|doctor|circuit|repair|setup ...', description: 'Configure, health-check, repair, and record circuit evidence for codex-lb provider auth without confusing ChatGPT OAuth and proxy keys.' },
     { name: 'zellij', usage: 'sks zellij status|repair [--json] | sks naruto dashboard latest | sks --mad', description: 'Inspect Zellij runtime status, explain repair (no auto-install), and open the SKS Zellij runtime used by MAD and Naruto lane UI.' },
-    { name: 'tmux', usage: 'sks tmux [--json]', description: 'Show the removed-runtime migration notice and point operators to Zellij.' },
+    { name: 'tmux', usage: 'removed-runtime migration notice (replacement: zellij)', description: 'Show the removed-runtime migration notice and point operators to Zellij.' },
     { name: 'mad-sks', usage: 'sks mad-sks plan|run|status|proof ... | sks --mad [--high]', description: 'Open or inspect MAD-SKS scoped permission workflows and the Zellij permission launcher.' },
     { name: 'auto-review', usage: 'sks auto-review status|enable|start [--high] | sks --Auto-review --high', description: 'Enable Codex automatic approval review and launch SKS Zellij with the auto-review profile.' },
     { name: 'dollar-commands', usage: 'sks dollar-commands [--json]', description: 'List Codex App $ commands such as $DFix and $Naruto.' },
@@ -707,6 +740,7 @@ export const COMMAND_CATALOG = [
     { name: 'init', usage: 'sks init [--force] [--local-only] [--install-scope global|project]', description: 'Initialize the local SKS control surface.' },
     { name: 'selftest', usage: 'sks selftest [--mock]', description: 'Run local smoke tests without calling a model.' },
     { name: 'goal', usage: 'sks goal create|pause|resume|clear|status ...', description: 'Prepare and control the fast SKS bridge overlay for Codex native persisted /goal workflows.' },
+    { name: 'seo-geo-optimizer', usage: 'sks seo-geo-optimizer [seo|geo] doctor|audit|plan|apply|verify|status|rollback|fixture [mission|latest] [--mode seo|geo] [--target auto|website|docs|package] [--json]', description: 'Run the unified SEO/GEO optimizer on the shared search-visibility kernel with mode-specific gates and proof.' },
     { name: 'research', usage: 'sks research prepare|run|status ...', description: 'Run long-form real research missions with xhigh agent Eureka ideas, debate, layered sources, paper, novelty, and falsification gates.' },
     { name: 'db', usage: 'sks db policy|scan|mcp-config|classify|check ...', description: 'Inspect and enforce database/Supabase safety policy.' },
     { name: 'eval', usage: 'sks eval run|compare|thresholds ...', description: 'Run deterministic context-quality and performance evidence checks.' },
@@ -748,6 +782,7 @@ export function routeByDollarCommand(commandName) {
     return ROUTES.find((route) => [
         dollarSkillName(route.command),
         ...(route.dollarAliases || []).map((alias) => dollarSkillName(alias)),
+        ...(route.hiddenDollarAliases || []).map((alias) => dollarSkillName(alias)),
         ...(route.appSkillAliases || [])
     ].includes(key)) || null;
 }
@@ -849,6 +884,23 @@ export function looksLikeImageUxReviewRequest(prompt = '') {
     const commandCue = /\$?(?:image-ux-review|ux-review|visual-review|ui-ux-review)\b/i.test(text);
     return commandCue || (reviewCue && imagegenCue);
 }
+export function looksLikeGeoLocationRequest(prompt = '') {
+    return /\b(?:geolocation|geoip|geo\s*ip|map\s+coordinates?|coordinates?|latitude|longitude|location\s+permission|cdn\s+edge\s+geography|regional?\s+redirect|country\s+routing|지도\s*좌표|위치\s*권한|지역\s*리다이렉트|국가별\s*라우팅)\b/i.test(String(prompt || ''));
+}
+export function looksLikeSeoRequest(prompt = '') {
+    const text = String(prompt || '');
+    return /\b(?:SEO|search\s+engine\s+optimization|technical\s+seo|canonical|sitemap|robots\.txt|hreflang|structured\s+data|json-ld|indexability|crawlability|metadata|meta\s+description|npm\s+seo|package\s+seo|검색\s*엔진\s*최적화|검색\s*노출|사이트맵|캐노니컬|구조화\s*데이터)\b/i.test(text);
+}
+export function looksLikeGenerativeEngineOptimizationRequest(prompt = '') {
+    if (looksLikeGeoLocationRequest(prompt))
+        return false;
+    const text = String(prompt || '');
+    return /\b(?:GEO|generative\s+engine\s+optimization|AI\s+(?:answer|search)\s+(?:visibility|discoverability)|LLM\s+(?:citation|answer|visibility|discoverability)|answerability|entity\s+(?:facts?|clarity)|claim\s+evidence|crawler\s+policy|OAI-SearchBot|GPTBot|ChatGPT-User|Claude-SearchBot|ClaudeBot|Claude-User|llms\.txt|AI\s*검색\s*가시성|AI\s*답변\s*가시성|생성형\s*엔진\s*최적화)\b/i.test(text);
+}
+export function looksLikeUltraSearchRequest(prompt = '') {
+    const text = String(prompt || '');
+    return /\b(?:UltraSearch|Ultra-Search|ultra\s*search|source\s+intelligence|provider-independent\s+source|source\s+acquisition|citation\s+proof|x-search)\b|울트라\s*서치|소스\s*인텔리전스/i.test(text);
+}
 export function routePrompt(prompt) {
     const text = stripVisibleDecisionAnswerBlocks(prompt);
     const command = dollarCommand(text);
@@ -896,7 +948,13 @@ export function routePrompt(prompt) {
         return routeById('Team');
     if (/\b(qa[-\s]?loop|qaloop|e2e\s+qa|qa\s+e2e)\b/i.test(text))
         return routeById('QALoop');
-    if (/\b(autoresearch|experiment|benchmark|SEO|GEO|ranking|optimi[sz]e|improve metric|discoverability|visibility|github stars?|npm downloads?|검색|노출|스타|다운로드)\b/i.test(text))
+    if (looksLikeUltraSearchRequest(text) && !looksLikeCodeChangingWork(text) && !looksLikeAnswerOnlyRequest(text))
+        return routeById('UltraSearch');
+    if (looksLikeGenerativeEngineOptimizationRequest(text))
+        return routeById('SEOGEOOptimizer');
+    if (looksLikeSeoRequest(text))
+        return routeById('SEOGEOOptimizer');
+    if (/\b(autoresearch|experiment|benchmark|ranking|optimi[sz]e|improve metric|github stars?|npm downloads?|스타|다운로드)\b/i.test(text))
         return routeById('AutoResearch');
     if (/\b(research|hypothesis|falsify|novelty|frontier|조사|연구)\b/i.test(text))
         return routeById('Research');
@@ -993,6 +1051,10 @@ export function routeRequiresSubagents(route, prompt = '') {
         return false;
     if (route.id === 'ImageUXReview')
         return false;
+    if (route.id === 'UltraSearch')
+        return false;
+    if (route.id === 'SEOGEOOptimizer')
+        return false;
     if (route.id === 'MadDB')
         return false;
     if (route.id === 'Research' || route.id === 'AutoResearch')
@@ -1027,7 +1089,7 @@ export function simpleGitOnlyRouteId(prompt = '') {
 }
 export function reflectionRequiredForRoute(route) {
     const id = String(route?.id || route?.mode || route?.route || route || '').replace(/^\$/, '');
-    return /^(team|naruto|shadowclone|shadow-clone|kagebunshin|kage-bunshin|qaloop|qa-loop|ppt|imageuxreview|image-ux-review|research|autoresearch|db|database|madsks|mad-sks|maddb|mad-db|gx)$/i.test(id);
+    return /^(team|naruto|shadowclone|shadow-clone|kagebunshin|kage-bunshin|qaloop|qa-loop|ppt|imageuxreview|image-ux-review|research|autoresearch|seo|geo|db|database|madsks|mad-sks|maddb|mad-db|gx)$/i.test(id);
 }
 export function looksLikeCodeChangingWork(prompt = '') {
     const text = String(prompt || '');
@@ -1075,9 +1137,13 @@ export function routeReasoning(route, prompt = '') {
         return teamRouteReasoning(text);
     if (route?.id === 'Research' || route?.id === 'AutoResearch')
         return reasoning('xhigh', 'research_or_experiment_route');
+    if (route?.id === 'UltraSearch')
+        return reasoning('high', 'source_intelligence_route');
+    if (route?.id === 'SEOGEOOptimizer')
+        return reasoning('high', 'search_visibility_route');
     if (route?.id === 'ImageUXReview')
         return reasoning('high', 'image_generation_visual_review_route');
-    if (/\b(research|autoresearch|hypothesis|falsify|novelty|frontier|benchmark|experiment|SEO|GEO|ranking|연구|실험|가설|검증)\b/i.test(text))
+    if (/\b(research|autoresearch|hypothesis|falsify|novelty|frontier|benchmark|experiment|ranking|연구|실험|가설|검증)\b/i.test(text))
         return reasoning('xhigh', 'research_level_prompt');
     if (base === 'xhigh')
         return reasoning('xhigh', 'route_policy_xhigh');

package/dist/core/search-visibility/adapter-registry.js

@@ -0,0 +1,26 @@
+import { auditSeo } from './analyzers.js';
+import { detectProject, discoverSiteInventory } from './discovery.js';
+import { verifySearchVisibility } from './verifier.js';
+class GenericSearchVisibilityAdapter {
+    id = 'generic-search-visibility';
+    async detect(ctx) {
+        return detectProject(ctx);
+    }
+    async discover(ctx, detection) {
+        return discoverSiteInventory(ctx, detection);
+    }
+    async audit(ctx, inventory) {
+        return auditSeo(ctx.root, inventory);
+    }
+    async verify(ctx, inventory) {
+        return verifySearchVisibility(ctx, inventory, null);
+    }
+}
+const GENERIC_ADAPTER = new GenericSearchVisibilityAdapter();
+export function adapterForDetection(_detection) {
+    return GENERIC_ADAPTER;
+}
+export function searchVisibilityAdapters() {
+    return [GENERIC_ADAPTER];
+}
+//# sourceMappingURL=adapter-registry.js.map

package/dist/core/search-visibility/adapters/next-app.js

@@ -0,0 +1,6 @@
+export const NEXT_APP_SEARCH_VISIBILITY_ADAPTER_ID = 'next-app';
+export const NEXT_APP_SEARCH_VISIBILITY_SUPPORT = {
+    sourceAudit: true,
+    mutation: 'guarded_metadata_robots_sitemap_jsonld_when_source_patterns_are_unambiguous',
+};
+//# sourceMappingURL=next-app.js.map

package/dist/core/search-visibility/adapters/next-pages.js

@@ -0,0 +1,6 @@
+export const NEXT_PAGES_SEARCH_VISIBILITY_ADAPTER_ID = 'next-pages';
+export const NEXT_PAGES_SEARCH_VISIBILITY_SUPPORT = {
+    sourceAudit: true,
+    mutation: 'guarded_metadata_robots_sitemap_jsonld_when_source_patterns_are_unambiguous',
+};
+//# sourceMappingURL=next-pages.js.map

package/dist/core/search-visibility/adapters/static-site.js

@@ -0,0 +1,6 @@
+export const STATIC_SITE_SEARCH_VISIBILITY_ADAPTER_ID = 'static-site';
+export const STATIC_SITE_SEARCH_VISIBILITY_SUPPORT = {
+    sourceAudit: true,
+    mutation: 'create_only_policy_files_and_managed_head_blocks_when_ownership_is_clear',
+};
+//# sourceMappingURL=static-site.js.map

package/dist/core/search-visibility/analyzers.js

@@ -0,0 +1,377 @@
+import path from 'node:path';
+import { readText, sha256 } from '../fsx.js';
+import { officialEvidence, sourceEvidence } from './discovery.js';
+export const GOOGLE_AI_FEATURES_URL = 'https://developers.google.com/search/docs/appearance/ai-features';
+export const GOOGLE_AI_OPTIMIZATION_URL = 'https://developers.google.com/search/docs/fundamentals/ai-optimization-guide';
+export const GOOGLE_STRUCTURED_DATA_URL = 'https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data';
+export const GOOGLE_STRUCTURED_DATA_POLICIES_URL = 'https://developers.google.com/search/docs/appearance/structured-data/sd-policies';
+export const GOOGLE_SITEMAP_URL = 'https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview';
+export const GOOGLE_HREFLANG_URL = 'https://developers.google.com/search/docs/specialty/international/localized-versions';
+export const GOOGLE_CANONICAL_URL = 'https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls';
+export const GOOGLE_ROBOTS_URL = 'https://developers.google.com/search/docs/crawling-indexing/robots/intro';
+export const GOOGLE_SPAM_POLICIES_URL = 'https://developers.google.com/search/docs/essentials/spam-policies';
+export const OPENAI_BOTS_URL = 'https://developers.openai.com/api/docs/bots';
+export const ANTHROPIC_CRAWLERS_URL = 'https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler';
+export const LLMS_TXT_URL = 'https://llmstxt.org/';
+export async function auditSeo(root, inventory) {
+    const findings = [];
+    const evidenceBase = packageOrInventoryEvidence(inventory);
+    if (inventory.target === 'package' || inventory.package.path) {
+        if (!inventory.package.description)
+            findings.push(finding('seo-package-description', 'metadata', 'medium', 'Package description is missing.', evidenceBase, ['package.json'], 'Add a concise factual package description.', true));
+        if (!inventory.package.keywords.length)
+            findings.push(finding('seo-package-keywords', 'metadata', 'low', 'Package keywords are missing.', evidenceBase, ['package.json'], 'Add source-backed npm keywords without stuffing.', true));
+        if (!inventory.package.repository)
+            findings.push(finding('seo-package-repository', 'metadata', 'medium', 'Repository metadata is missing.', evidenceBase, ['package.json'], 'Set package.json repository to the public project URL.', true));
+        if (!inventory.readme.h1)
+            findings.push(finding('seo-readme-h1', 'package-docs', 'medium', 'README H1 is missing.', evidenceBase, [inventory.readme.path || 'README.md'], 'Add a clear H1 matching the package/entity name.', false));
+        if (!inventory.readme.command_mentions.length)
+            findings.push(finding('seo-readme-quickstart', 'package-docs', 'low', 'README quickstart command surface is hard to detect.', evidenceBase, [inventory.readme.path || 'README.md'], 'Include exact install and command spellings.', false));
+    }
+    const robots = inventory.policy_files.filter((file) => file.kind === 'robots' && file.exists);
+    const sitemap = inventory.policy_files.filter((file) => file.kind === 'sitemap' && file.exists);
+    if (inventory.target !== 'package') {
+        if (!robots.length)
+            findings.push(finding('seo-robots-missing', 'indexability', 'low', 'robots.txt was not found; this is not a security issue, but crawl policy is undocumented.', [officialEvidence(GOOGLE_ROBOTS_URL, 'robots.txt is crawl management, not a private-content protection mechanism')], ['robots.txt'], 'Create a managed robots.txt only when project ownership is clear.', true, 'robotsMutation'));
+        if (!sitemap.length)
+            findings.push(finding('seo-sitemap-missing', 'sitemap', 'medium', 'Sitemap was not found; sitemap discovery signals are absent.', [officialEvidence(GOOGLE_SITEMAP_URL, 'Sitemaps help discovery but do not guarantee indexing')], ['sitemap.xml'], 'Create a sitemap from confirmed canonical/indexable routes.', true, 'sitemapMutation'));
+    }
+    for (const html of inventory.html_files) {
+        const evidence = [sourceEvidence(html.path, 'HTML file inspected')];
+        if (!html.title)
+            findings.push(finding(`seo-title-missing-${slug(html.path)}`, 'metadata', 'medium', `HTML page ${html.path} is missing a title.`, evidence, [html.path], 'Add a factual title aligned with visible page intent.', true, 'metadataMutation'));
+        if (!html.description)
+            findings.push(finding(`seo-description-missing-${slug(html.path)}`, 'metadata', 'low', `HTML page ${html.path} is missing a meta description.`, evidence, [html.path], 'Add a concise factual meta description.', true, 'metadataMutation'));
+        if (!html.canonical && inventory.origin)
+            findings.push(finding(`seo-canonical-missing-${slug(html.path)}`, 'canonical', 'medium', `HTML page ${html.path} has no canonical URL.`, [sourceEvidence(html.path, 'No canonical link found'), officialEvidence(GOOGLE_CANONICAL_URL, 'Canonical links are signals for preferred duplicate URLs')], [html.path], 'Add an absolute canonical URL only from a verified canonical host.', true, 'metadataMutation'));
+        if (html.canonical && !/^https?:\/\//i.test(html.canonical))
+            findings.push(finding(`seo-canonical-relative-${slug(html.path)}`, 'canonical', 'medium', `HTML page ${html.path} uses a non-absolute canonical URL.`, [sourceEvidence(html.path, `canonical=${html.canonical}`)], [html.path], 'Prefer absolute canonical URLs derived from the verified origin.', true, 'metadataMutation'));
+        if (html.jsonLdParseErrors.length)
+            findings.push(finding(`seo-jsonld-parse-${slug(html.path)}`, 'structured-data', 'high', `HTML page ${html.path} has invalid JSON-LD.`, evidence, [html.path], 'Fix JSON syntax before rich-result eligibility claims.', false, 'structuredDataMutation'));
+        if (html.jsonLdCount && !html.visibleTextSample)
+            findings.push(finding(`seo-jsonld-visible-parity-${slug(html.path)}`, 'structured-data', 'high', `HTML page ${html.path} has JSON-LD but little visible text evidence.`, [sourceEvidence(html.path, 'Structured data must describe visible/source-backed content'), officialEvidence(GOOGLE_STRUCTURED_DATA_POLICIES_URL, 'Structured data quality guidelines require truthful page content')], [html.path], 'Verify visible-content parity before adding or relying on structured data.', false));
+        for (const href of html.links) {
+            if (href.startsWith('/') && href !== '/' && href.includes('//'))
+                findings.push(finding(`seo-link-variant-${slug(html.path)}-${slug(href)}`, 'internal-links', 'low', `Internal link ${href} may contain a malformed duplicate slash variant.`, evidence, [html.path], 'Normalize internal links to canonical route variants.', true));
+        }
+    }
+    if (inventory.locale_candidates.length > 1 && !inventory.html_files.some((html) => /alternate/i.test(html.visibleTextSample) || html.links.some((href) => /hreflang/i.test(href)))) {
+        findings.push(finding('seo-locale-hreflang-unverified', 'locale', 'medium', 'Multiple locale candidates exist, but hreflang reciprocity is not verified from source inventory.', [officialEvidence(GOOGLE_HREFLANG_URL, 'Localized versions should provide self/reciprocal alternate signals where applicable')], inventory.locale_candidates.map((candidate) => candidate.source), 'Verify self, reciprocal, and x-default locale graph before mutating locale metadata.', false, 'localeMutation'));
+    }
+    const unsupportedClaims = unsupportedRankingClaims(inventory);
+    for (const claim of unsupportedClaims) {
+        findings.push(finding(`seo-unsupported-claim-${slug(claim.path)}`, 'truthfulness', 'critical', `Unsupported ranking/traffic guarantee found in ${claim.path}.`, [sourceEvidence(claim.path, claim.text)], [claim.path], 'Remove ranking, traffic, citation, or indexing guarantees unless backed by measured evidence.', false));
+    }
+    return findings;
+}
+export async function auditGeo(root, inventory) {
+    const entityFacts = await buildEntityFacts(root, inventory);
+    const claims = await buildClaimEvidence(root, inventory, entityFacts);
+    const crawlers = buildCrawlerPolicyRegistry();
+    const findings = [];
+    const baseEvidence = packageOrInventoryEvidence(inventory);
+    if (!entityFacts.canonical_name)
+        findings.push(finding('geo-entity-name-missing', 'entity-facts', 'high', 'Canonical entity name could not be established from source evidence.', baseEvidence, ['package.json', 'README.md'], 'Add or align source-backed entity naming before GEO publishing claims.', false));
+    if (!entityFacts.facts.length)
+        findings.push(finding('geo-entity-facts-empty', 'entity-facts', 'high', 'No source-backed entity facts were found.', baseEvidence, ['package.json', 'README.md'], 'Record official entity facts with visible source locations.', false));
+    if (entityFacts.conflicts.length)
+        findings.push(finding('geo-entity-fact-conflict', 'entity-facts', 'high', 'Entity facts conflict across package/docs/source evidence.', baseEvidence, entityFacts.conflicts.flatMap((conflict) => conflict.sources), 'Resolve conflicting names, URLs, or claims before generating structured or llms.txt outputs.', false));
+    const unsafeClaims = claims.filter((claim) => !claim.safe_to_publish);
+    for (const claim of unsafeClaims) {
+        findings.push(finding(`geo-unsafe-claim-${slug(claim.id)}`, 'claim-evidence', 'critical', `Claim is not safe to publish: ${claim.claim}`, [sourceEvidence(claim.supporting_source, claim.claim, claim.source_hash)], [claim.supporting_source], 'Do not publish commercial, ranking, pricing, review, or availability claims without source evidence and visible parity.', false));
+    }
+    if (!inventory.html_files.length && !inventory.readme.path)
+        findings.push(finding('geo-answerability-no-visible-source', 'answerability', 'medium', 'No visible README or HTML answer surface was found.', baseEvidence, ['README.md', 'index.html'], 'Add human-visible source content before AI answerability claims.', false));
+    const llms = inventory.policy_files.find((file) => file.kind === 'llms' && file.exists);
+    if (!llms) {
+        findings.push(finding('geo-llms-txt-optional-missing', 'llms-txt', 'info', 'llms.txt is absent; this is not a blocker because llms.txt is optional and experimental.', [officialEvidence(LLMS_TXT_URL, 'llms.txt is a proposal for optional inference-time guidance'), officialEvidence(GOOGLE_AI_OPTIMIZATION_URL, 'Google generative AI search does not require special AI schema or files')], ['llms.txt'], 'Only plan llms.txt when explicitly requested with --include-llms-txt --apply.', true));
+    }
+    else if (!llms.managed) {
+        findings.push(finding('geo-llms-txt-user-authored', 'llms-txt', 'medium', 'Existing llms.txt has no SKS managed marker; full overwrite is blocked.', [sourceEvidence(llms.path, 'Existing llms.txt is user-authored or unmanaged', llms.hash)], [llms.path], 'Preserve user-authored content and use managed merge only when ownership is clear.', false));
+    }
+    const answerability = buildAnswerabilityReport(inventory, entityFacts, claims);
+    return { findings, entityFacts, claims, crawlers, answerability };
+}
+export function buildRouteGraph(inventory) {
+    return {
+        schema: 'sks.search-visibility.route-graph.v1',
+        routes: inventory.routes,
+        canonical_edges: inventory.html_files.filter((html) => html.canonical).map((html) => ({ from: routeFromHtmlPath(html.path), to: String(html.canonical), source: html.path })),
+        internal_links: inventory.html_files.flatMap((html) => html.links.filter((href) => href.startsWith('/')).map((href) => ({ from: routeFromHtmlPath(html.path), to: href, source: html.path }))),
+        redirects: [],
+        generated_at: new Date().toISOString(),
+    };
+}
+export function buildCanonicalMap(inventory) {
+    return {
+        schema: 'sks.search-visibility.canonical-map.v1',
+        generated_at: new Date().toISOString(),
+        origin: inventory.origin,
+        groups: inventory.html_files.map((html) => ({
+            source: html.path,
+            route: routeFromHtmlPath(html.path),
+            canonical: html.canonical,
+            confidence: html.canonical ? 0.9 : 0.3,
+            note: html.canonical ? 'source canonical observed' : 'canonical missing or not verified',
+        })),
+        warning: 'Canonical signals express preference; final search-engine canonical selection is not guaranteed.',
+    };
+}
+export function buildLocaleGraph(inventory) {
+    return {
+        schema: 'sks.search-visibility.locale-graph.v1',
+        generated_at: new Date().toISOString(),
+        locales: inventory.locale_candidates,
+        checks: {
+            self_hreflang_verified: false,
+            reciprocal_hreflang_verified: false,
+            x_default_verified: false,
+            localized_sitemap_rows_verified: false,
+        },
+        unverified: inventory.locale_candidates.length ? ['hreflang reciprocity requires framework/source-specific verification'] : [],
+    };
+}
+export function buildSitemapAudit(inventory) {
+    const files = inventory.policy_files.filter((file) => file.kind === 'sitemap' && file.exists);
+    return {
+        schema: 'sks.search-visibility.sitemap-audit.v1',
+        generated_at: new Date().toISOString(),
+        sitemap_files: files,
+        route_count: inventory.routes.length,
+        status: files.length ? 'present_unverified_rows' : 'missing',
+        indexing_guarantee: false,
+        note: 'Sitemaps are discovery signals and do not guarantee indexing.',
+    };
+}
+export function buildRobotsPolicy(inventory, crawlers = buildCrawlerPolicyRegistry()) {
+    return {
+        schema: 'sks.search-visibility.robots-policy.v1',
+        generated_at: new Date().toISOString(),
+        robots_files: inventory.policy_files.filter((file) => file.kind === 'robots'),
+        crawler_policy_sources: crawlers,
+        security_note: 'robots.txt is crawl management, not authentication or private-content protection.',
+        mutations_blocked_when_unmanaged: true,
+    };
+}
+export function buildStructuredDataLedger(inventory) {
+    return {
+        schema: 'sks.search-visibility.structured-data-ledger.v1',
+        generated_at: new Date().toISOString(),
+        pages: inventory.html_files.map((html) => ({
+            path: html.path,
+            json_ld_count: html.jsonLdCount,
+            parse_errors: html.jsonLdParseErrors,
+            visible_text_sample_present: Boolean(html.visibleTextSample),
+            visible_content_parity: html.jsonLdCount ? (html.visibleTextSample ? 'needs_field_level_review' : 'blocked') : 'not_applicable',
+        })),
+        policies: [GOOGLE_STRUCTURED_DATA_URL, GOOGLE_STRUCTURED_DATA_POLICIES_URL],
+    };
+}
+export function buildInternalLinkGraph(inventory) {
+    return {
+        schema: 'sks.search-visibility.internal-link-graph.v1',
+        generated_at: new Date().toISOString(),
+        links: inventory.html_files.flatMap((html) => html.links.map((href) => ({ source: html.path, href, internal: href.startsWith('/') }))),
+        orphan_routes: inventory.routes.filter((route) => !inventory.html_files.some((html) => html.links.includes(route.path))).map((route) => route.path),
+    };
+}
+export function buildAiCrawlerPolicy() {
+    return {
+        schema: 'sks.search-visibility.ai-crawler-policy.v1',
+        generated_at: new Date().toISOString(),
+        entries: buildCrawlerPolicyRegistry(),
+        policy: {
+            single_allow_ai_toggle: false,
+            training_auto_allow: false,
+            purpose_split_required: true,
+            stale_registry_blocks_mutation: true,
+        },
+    };
+}
+export function buildLlmsTxtPlan(inventory, facts) {
+    const existing = inventory.policy_files.find((file) => file.kind === 'llms' && file.exists);
+    return {
+        schema: 'sks.search-visibility.llms-txt-plan.v1',
+        generated_at: new Date().toISOString(),
+        status: existing && !existing.managed ? 'blocked_user_authored_file' : 'optional_candidate',
+        experimental_assistive_surface: true,
+        required_for_gate: false,
+        source: LLMS_TXT_URL,
+        candidate_facts: facts.facts,
+        privacy_check: {
+            private_urls_included: false,
+            credentials_included: false,
+        },
+        blockers: existing && !existing.managed ? ['existing_llms_txt_without_managed_marker'] : [],
+    };
+}
+async function buildEntityFacts(root, inventory) {
+    const now = new Date().toISOString();
+    const facts = [];
+    if (inventory.package.name)
+        facts.push(entityFact('official_package_name', inventory.package.name, 'package.json#name', [inventory.package.path || 'package.json'], now));
+    if (inventory.package.description)
+        facts.push(entityFact('official_description', inventory.package.description, 'package.json#description', [inventory.package.path || 'package.json'], now));
+    if (inventory.package.repository)
+        facts.push(entityFact('official_repository', inventory.package.repository, 'package.json#repository', [inventory.package.path || 'package.json'], now));
+    if (inventory.package.homepage)
+        facts.push(entityFact('official_homepage', inventory.package.homepage, 'package.json#homepage', [inventory.package.path || 'package.json'], now));
+    if (inventory.readme.h1)
+        facts.push(entityFact('readme_heading', inventory.readme.h1, `${inventory.readme.path || 'README.md'}#h1`, [inventory.readme.path || 'README.md'], now));
+    const conflicts = detectFactConflicts(facts);
+    const canonicalName = inventory.readme.h1 || inventory.package.name;
+    const canonicalUrl = inventory.package.homepage || inventory.package.repository || inventory.origin;
+    return {
+        schema: 'sks.search-visibility.entity-facts.v1',
+        entity_id: canonicalName ? `entity:${slug(canonicalName)}` : 'entity:unknown',
+        type: inventory.package.bin.length ? 'SoftwareApplication' : 'Unknown',
+        canonical_name: canonicalName,
+        canonical_url: canonicalUrl,
+        facts,
+        conflicts,
+    };
+}
+async function buildClaimEvidence(root, inventory, facts) {
+    const claims = facts.facts.map((fact, index) => ({
+        id: `claim-${String(index + 1).padStart(3, '0')}`,
+        claim: `${fact.key}: ${fact.value}`,
+        claim_type: fact.key.includes('repository') || fact.key.includes('homepage') ? 'supporting_source' : 'identity',
+        supporting_source: fact.source,
+        source_hash: null,
+        visible_location: fact.visible_on[0] || null,
+        confidence: fact.confidence,
+        freshness: fact.freshness,
+        contradiction: null,
+        safe_to_publish: true,
+        verification_level: 'locally_verified',
+    }));
+    const unsupported = unsupportedRankingClaims(inventory);
+    for (const item of unsupported) {
+        const full = path.join(root, item.path);
+        const text = await readText(full, '');
+        claims.push({
+            id: `unsafe-${slug(item.path)}`,
+            claim: item.text,
+            claim_type: 'capability',
+            supporting_source: item.path,
+            source_hash: text ? sha256(text) : null,
+            visible_location: item.path,
+            confidence: 0.9,
+            freshness: 'unknown',
+            contradiction: 'Unsupported ranking, traffic, indexing, or AI citation outcome claim.',
+            safe_to_publish: false,
+            verification_level: 'implemented',
+        });
+    }
+    return claims;
+}
+function buildAnswerabilityReport(inventory, facts, claims) {
+    const questions = [
+        {
+            representative_question: `What is ${facts.canonical_name || inventory.package.name || 'this project'}?`,
+            intent_class: 'entity_identity',
+            official_answer_page: inventory.readme.path || inventory.html_files[0]?.path || null,
+            answer_section: inventory.readme.h1 || inventory.html_files[0]?.title || null,
+            supporting_claim_ids: claims.filter((claim) => claim.safe_to_publish).slice(0, 5).map((claim) => claim.id),
+            source_freshness: 'stable',
+            internal_discovery_path: inventory.readme.path ? ['README.md'] : inventory.routes.map((route) => route.path).slice(0, 5),
+            text_availability: Boolean(inventory.readme.path || inventory.html_files.some((html) => html.visibleTextSample)),
+            structured_entity_linkage: facts.canonical_url ? 'present_source_backed' : 'missing',
+            gaps: facts.facts.length ? [] : ['entity_facts_missing'],
+        },
+    ];
+    return {
+        schema: 'sks.search-visibility.answerability-report.v1',
+        generated_at: new Date().toISOString(),
+        questions,
+        ranking_or_citation_claim: false,
+        external_observation: 'not_verified',
+    };
+}
+function buildCrawlerPolicyRegistry() {
+    const observedAt = '2026-06-26T00:00:00.000Z';
+    const expiresAt = '2026-09-24T00:00:00.000Z';
+    return [
+        crawler('OAI-SearchBot', 'OpenAI', 'search', OPENAI_BOTS_URL, observedAt, expiresAt, 'Used for ChatGPT search visibility; robots.txt can express crawl preference for this user agent.'),
+        crawler('GPTBot', 'OpenAI', 'training', OPENAI_BOTS_URL, observedAt, expiresAt, 'Used for model training related crawling; do not auto-allow training crawler without user choice.'),
+        crawler('ChatGPT-User', 'OpenAI', 'user_retrieval', OPENAI_BOTS_URL, observedAt, expiresAt, 'User-directed retrieval agent; not the same as search-index eligibility.'),
+        crawler('OAI-AdsBot', 'OpenAI', 'ads_validation', OPENAI_BOTS_URL, observedAt, expiresAt, 'Ads/policy validation crawler; separated from search and training purposes.'),
+        crawler('Claude-SearchBot', 'Anthropic', 'search', ANTHROPIC_CRAWLERS_URL, observedAt, expiresAt, 'Search indexing crawler for Claude search surfaces.'),
+        crawler('ClaudeBot', 'Anthropic', 'training', ANTHROPIC_CRAWLERS_URL, observedAt, expiresAt, 'Model development/training crawler; do not auto-allow without user choice.'),
+        crawler('Claude-User', 'Anthropic', 'user_retrieval', ANTHROPIC_CRAWLERS_URL, observedAt, expiresAt, 'User-directed retrieval agent; policy semantics differ from search crawler.'),
+    ];
+}
+function crawler(userAgent, provider, purpose, officialSource, observedAt, expiresAt, robotsSemantics) {
+    return { userAgent, provider, purpose, officialSource, observedAt, expiresAt, robotsSemantics };
+}
+function packageOrInventoryEvidence(inventory) {
+    if (inventory.package.path)
+        return [sourceEvidence(inventory.package.path, 'package metadata inspected')];
+    if (inventory.readme.path)
+        return [sourceEvidence(inventory.readme.path, 'README inspected')];
+    return [sourceEvidence('.', 'project inventory inspected')];
+}
+function finding(ruleId, category, severity, summary, evidence, affected, remediation, autoFixable, requiredCapability) {
+    const result = {
+        id: `F-${ruleId}`,
+        ruleId,
+        domain: ruleId.startsWith('geo') ? 'geo' : ruleId.startsWith('seo') ? 'seo' : 'shared',
+        category,
+        severity,
+        confidence: evidence.length ? 0.9 : 0.4,
+        blocking: severity === 'critical',
+        summary,
+        evidence,
+        affected,
+        remediation,
+        autoFixable,
+        status: evidence.length ? 'confirmed' : 'not_verified',
+    };
+    if (requiredCapability)
+        result.requiredCapability = requiredCapability;
+    return result;
+}
+function unsupportedRankingClaims(inventory) {
+    const out = [];
+    const candidates = [
+        ...(inventory.package.description ? [{ path: inventory.package.path || 'package.json', text: inventory.package.description }] : []),
+        ...(inventory.readme.h1 ? [{ path: inventory.readme.path || 'README.md', text: inventory.readme.h1 }] : []),
+    ];
+    for (const html of inventory.html_files) {
+        if (html.visibleTextSample)
+            candidates.push({ path: html.path, text: html.visibleTextSample });
+    }
+    for (const candidate of candidates) {
+        if (/(guarantee[ds]?|보장|1위|#1|top\s*rank|rank\s*#?1|traffic\s+(?:lift|increase)|AI\s+(?:citation|answer)\s+guarantee|검색\s*유입\s*증가\s*보장|인용\s*보장)/i.test(candidate.text))
+            out.push(candidate);
+    }
+    return out;
+}
+function detectFactConflicts(facts) {
+    const byKey = new Map();
+    for (const fact of facts) {
+        const key = fact.key.replace(/^readme_heading$/, 'official_package_name');
+        const current = byKey.get(key) || [];
+        current.push(fact);
+        byKey.set(key, current);
+    }
+    const conflicts = [];
+    for (const [key, rows] of byKey) {
+        const values = Array.from(new Set(rows.map((row) => row.value).filter(Boolean)));
+        if (values.length > 1)
+            conflicts.push({ key, values, sources: rows.map((row) => row.source) });
+    }
+    return conflicts;
+}
+function entityFact(key, value, source, visibleOn, observedAt) {
+    return { key, value, source, visible_on: visibleOn, observed_at: observedAt, confidence: 1, freshness: 'stable' };
+}
+function routeFromHtmlPath(pathValue) {
+    const clean = pathValue.replace(/^public\//, '').replace(/index\.html$/, '').replace(/\.html$/, '');
+    const route = `/${clean}`.replace(/\/+/g, '/');
+    return route === '/' ? '/' : route.replace(/\/$/, '');
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 64) || 'item';
+}
+//# sourceMappingURL=analyzers.js.map