@nebulacomponents/citable 0.1.0

package/src/commands/mapClaims.js

@@ -0,0 +1,89 @@
+import { buildContext } from './context.js';
+import { loadRegistries, saveRegistry, diffRegistries } from '../registries/index.js';
+import { nowIso } from '../shared/io.js';
+
+const PATTERNS = [
+  { rx: /\b(the (best|leading|top|fastest|most \w+)|#1|number one|industry[- ]leading|world[- ]class|first and only|unmatched|unrivalled|unrivaled)\b/i, type: 'comparative', why: 'superlative / market-position language' },
+  { rx: /\b\d+(\.\d+)?\s*(%|percent|x|times)\b/i, type: 'performance', why: 'quantitative assertion' },
+  { rx: /\b(guarantee[ds]?|ensures?|always|never fails?|zero (downtime|risk)|100%)\b/i, type: 'performance', why: 'absolute or guarantee language' },
+  { rx: /\b(compliant|certified|SOC ?2|ISO ?\d+|GDPR|HIPAA|PCI[- ]DSS|FedRAMP|accredited)\b/i, type: 'legal_regulatory', why: 'compliance / certification assertion' },
+  { rx: /\b(secure|encrypt(s|ed|ion)|zero[- ]trust|penetration[- ]tested|audited)\b/i, type: 'security', why: 'security capability assertion' },
+  { rx: /\b(only (platform|solution|product|vendor)|unlike (any|all) (other|competitors))\b/i, type: 'comparative', why: 'exclusivity assertion' },
+  { rx: /\b(trusted by|used by|customers? (include|like)|deployed (at|by))\b/i, type: 'commercial', why: 'customer / adoption assertion' },
+  { rx: /\b(integrates? with|supports? (over )?\d+|compatible with)\b/i, type: 'capability', why: 'capability / integration assertion' },
+];
+
+const REVIEW_TYPES = new Set(['legal_regulatory', 'security', 'commercial']);
+
+/**
+ * `citable map-claims` — extract MATERIAL claim candidates from page text.
+ * Candidates are never marked verified; regulated types are flagged review_required.
+ * Writes to the claim registry only when `write: true`.
+ */
+export async function mapClaims(root, { target, baseUrl, write = false, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('map-claims requires a site target (built output directory or URL)');
+
+  const existing = new Set((ctx.registries.claims?.entries || []).map((c) => normalizeText(c.claim)));
+  const candidates = [];
+  for (const p of ctx.site.pages) {
+    if (p.status !== 200) continue;
+    const sentences = p.paragraphs.flatMap((para) => para.split(/(?<=[.!?])\s+(?=[A-Z])/));
+    for (const s of sentences) {
+      if (s.length < 25 || s.length > 400) continue; // not every sentence is a strategic claim
+      for (const pat of PATTERNS) {
+        if (pat.rx.test(s)) {
+          if (existing.has(normalizeText(s))) break;
+          candidates.push({
+            claim: s.trim(),
+            claim_type: pat.type,
+            reason: pat.why,
+            source_location: `${p.sourceFile ?? p.url}`,
+            page_url: p.url,
+            review_required: REVIEW_TYPES.has(pat.type),
+          });
+          break; // one classification per sentence
+        }
+      }
+    }
+  }
+
+  // Deduplicate by normalized text
+  const seen = new Set();
+  const unique = candidates.filter((c) => {
+    const k = normalizeText(c.claim);
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+
+  let registryDiff = null;
+  if (write && unique.length) {
+    const { registries } = loadRegistries(root);
+    const before = JSON.parse(JSON.stringify(registries.claims));
+    let n = registries.claims.entries.length;
+    for (const c of unique) {
+      n += 1;
+      registries.claims.entries.push({
+        claim_id: `CLAIM-${String(n).padStart(4, '0')}`,
+        claim: c.claim,
+        claim_type: c.claim_type,
+        entity: undefined,
+        evidence: [],
+        publication_surfaces: [c.page_url],
+        source_location: c.source_location,
+        status: c.review_required ? 'review_required' : 'candidate',
+        legal_status: c.review_required ? 'review_required' : 'not_assessed',
+        provenance: { created: nowIso(), created_by: 'citable map-claims', source: c.reason },
+      });
+    }
+    saveRegistry(root, 'claims', registries.claims);
+    registryDiff = diffRegistries(before, registries.claims, 'claim_id');
+  }
+
+  return { candidates: unique, written: write ? unique.length : 0, registryDiff };
+}
+
+function normalizeText(s) {
+  return String(s).toLowerCase().replace(/\s+/g, ' ').trim();
+}

package/src/commands/schemaCmd.js

@@ -0,0 +1,71 @@
+import { buildContext } from './context.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors, sitePageFor } from '../detectors/framework.js';
+
+/**
+ * `citable schema` — derive JSON-LD proposals from registry data and validate deployed schema.
+ *
+ * Generation is registry-driven: schema is only proposed for entities that exist in the
+ * entity registry with a canonical URL. Nothing is fabricated; missing fields are listed
+ * as required_input instead of being invented.
+ */
+export async function schemaCommand(root, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+
+  // 1. Validate deployed schema via SCHEMA + ENTITY detectors (needs a site)
+  let findings = [];
+  if (ctx.site) {
+    const res = runDetectors(selectDetectors({ namespaces: ['SCHEMA', 'ENTITY'] }).filter((d) => !d.requires || d.requires.every((r) => ctx[r])), ctx);
+    findings = res.findings;
+  }
+
+  // 2. Propose JSON-LD from registry entities
+  const proposals = [];
+  const blocked = [];
+  const base = ctx.config?.site?.base_url;
+  for (const e of (ctx.registries.entities?.entries || []).filter((e) => e.status !== 'retired')) {
+    const missing = [];
+    if (!e.canonical_url) missing.push('canonical_url');
+    if (!e.definition && ['proprietary_concept', 'category'].includes(e.entity_type)) missing.push('definition');
+    if (missing.length) {
+      blocked.push({ entity_id: e.entity_id, status: 'blocked', reason: 'entity record incomplete; schema would require invented facts', required_input: missing });
+      continue;
+    }
+    const id = `${e.canonical_url}#${e.entity_type}`;
+    const typeMap = {
+      organization: 'Organization', legal_entity: 'Organization', person: 'Person', author: 'Person',
+      product: 'SoftwareApplication', product_family: 'SoftwareApplication', service: 'Service',
+      category: 'DefinedTerm', proprietary_concept: 'DefinedTerm', methodology: 'DefinedTerm',
+      research_artifact: 'Report', dataset: 'Dataset', location: 'Place', partnership: 'Organization', case_study: 'Article',
+    };
+    const block = {
+      '@context': 'https://schema.org',
+      '@type': (e.schema_types && e.schema_types[0]) || typeMap[e.entity_type] || 'Thing',
+      '@id': id,
+      name: e.canonical_name,
+      url: e.canonical_url,
+    };
+    if (e.definition) block.description = e.definition;
+    if (e.aliases?.length) block.alternateName = e.aliases;
+    if ((e.authoritative_profiles || []).length) block.sameAs = e.authoritative_profiles;
+    if (e.owner_entity) {
+      const owner = (ctx.registries.entities?.entries || []).find((o) => o.entity_id === e.owner_entity);
+      if (owner?.canonical_url) block.publisher = { '@id': `${owner.canonical_url}#${owner.entity_type}` };
+    }
+    // consistency: schema must not exceed the registry — no ratings, prices, or claims added here
+    proposals.push({ entity_id: e.entity_id, target_url: e.canonical_url, jsonld: block });
+  }
+
+  // 3. Detect registry entities whose canonical page carries no schema at all
+  const missingDeployment = [];
+  if (ctx.site) {
+    for (const p of proposals) {
+      const page = sitePageFor(ctx, { url: p.target_url });
+      if (page && page.jsonLd.length === 0) {
+        missingDeployment.push({ entity_id: p.entity_id, url: p.target_url, note: 'canonical page has no JSON-LD; proposal available' });
+      }
+    }
+  }
+
+  return { findings, proposals, blocked, missingDeployment };
+}

package/src/commands/substantiate.js

@@ -0,0 +1,121 @@
+import { loadRegistries, saveRegistry, diffRegistries } from '../registries/index.js';
+import { isPastDate, nowIso } from '../shared/io.js';
+
+const REGULATED = new Set(['legal_regulatory', 'security', 'commercial']);
+
+/**
+ * `citable substantiate` — deterministic claim/evidence assessment.
+ *
+ * Outcomes per claim (spec §8.5): verified · verified_narrowed · insufficient_evidence ·
+ * contradicted · expired · prohibited · review_required.
+ *
+ * This command performs the *deterministic* portion: evidence linkage, validity dates,
+ * type adequacy, contradiction records, and legal-review gating. It never invents evidence
+ * and never upgrades a claim to verified on its own — upgrades require existing verified
+ * evidence in the registry. Semantic adequacy (does the evidence actually support the
+ * wording?) is a human/rubric task: see skill/rubrics/evidence-strength.md.
+ */
+export function substantiate(root, { write = false, refDate } = {}) {
+  const { registries, problems } = loadRegistries(root);
+  const ref = refDate ? new Date(refDate) : new Date();
+  const evidence = new Map(registries.evidence.entries.map((e) => [e.evidence_id, e]));
+  const before = JSON.parse(JSON.stringify(registries.claims));
+  const assessments = [];
+
+  for (const c of registries.claims.entries) {
+    const a = { claim_id: c.claim_id, previous_status: c.status, outcome: null, reasons: [], required_input: [] };
+
+    if (c.legal_status === 'prohibited') {
+      a.outcome = 'prohibited';
+      a.reasons.push('legal_status is prohibited');
+    } else if (isPastDate(c.expires, ref)) {
+      a.outcome = 'expired';
+      a.reasons.push(`claim expiry ${c.expires} has passed`);
+    } else if ((c.contradictory_sources || []).length > 0) {
+      a.outcome = 'contradicted';
+      a.reasons.push(`contradictory sources recorded: ${c.contradictory_sources.join(', ')}`);
+    } else if (REGULATED.has(c.claim_type) && (!c.legal_status || c.legal_status === 'not_assessed')) {
+      a.outcome = 'review_required';
+      a.reasons.push(`${c.claim_type} claim requires legal/SME review before any verified status`);
+      a.required_input.push('legal or subject-matter review decision');
+    } else if (['opinion', 'position', 'aspirational'].includes(c.claim_type)) {
+      // Opinions and aspirations are positions, not verifiable facts; they never enter the verified track.
+      a.outcome = c.status === 'candidate' ? 'candidate' : 'unverified';
+      a.reasons.push(`${c.claim_type} claims are positions, not verifiable facts; keep them out of the verified track`);
+    } else {
+      const evs = (c.evidence || []).map((id) => evidence.get(id)).filter(Boolean);
+      const missing = (c.evidence || []).filter((id) => !evidence.has(id));
+      const live = evs.filter((e) => !isPastDate(e.valid_until, ref) && ['verified', 'reviewed'].includes(e.verification_status));
+      if (missing.length) a.reasons.push(`dangling evidence references: ${missing.join(', ')}`);
+      if (evs.length === 0) {
+        a.outcome = 'insufficient_evidence';
+        a.reasons.push('no resolvable evidence attached');
+        a.required_input.push(...requiredInputFor(c));
+      } else if (live.length === 0) {
+        a.outcome = 'insufficient_evidence';
+        a.reasons.push('all attached evidence is expired, unverified, revoked, or inaccessible');
+        a.required_input.push('current, verified evidence');
+      } else if (['performance', 'comparative', 'security'].includes(c.claim_type) && live.every((e) => e.primary_or_secondary === 'secondary')) {
+        a.outcome = 'insufficient_evidence';
+        a.reasons.push(`${c.claim_type} claims require primary evidence; only secondary evidence attached`);
+        a.required_input.push('primary evidence (test result, benchmark, specification, certification)');
+      } else if (['performance'].includes(c.claim_type) && live.every((e) => !e.methodology)) {
+        a.outcome = 'insufficient_evidence';
+        a.reasons.push('performance evidence lacks methodology');
+        a.required_input.push('methodology', 'test conditions', 'measurement period');
+      } else if ((c.scope || []).length === 0 && ['capability', 'performance', 'comparative'].includes(c.claim_type)) {
+        a.outcome = 'verified_narrowed';
+        a.reasons.push('evidence exists but claim declares no scope; treat as verified only with narrowed scope pending scope definition');
+        a.required_input.push('explicit scope and exclusions');
+      } else {
+        // Deterministic conditions passed. Verified status additionally requires a recorded
+        // semantic support assessment (entailment) by a named assessor — evidence linkage
+        // alone does not establish that the wording matches what the evidence proves.
+        const sa = c.support_assessment;
+        if (sa?.status === 'contradicted') {
+          a.outcome = 'contradicted';
+          a.reasons.push('support assessment records the evidence as contradicting the claim wording');
+        } else if (['verified', 'verified_narrowed'].includes(c.status)) {
+          if (sa && ['directly_supported', 'partially_supported'].includes(sa.status) && sa.assessor) {
+            a.outcome = sa.status === 'partially_supported' ? 'verified_narrowed' : c.status;
+            a.reasons.push(`deterministic conditions hold; support assessment ${sa.status} by ${sa.assessor}`);
+          } else {
+            a.outcome = 'review_required';
+            a.reasons.push('verified status held without an adequate semantic support assessment; entailment review required (evidence-strength rubric)');
+            a.required_input.push('support_assessment with named assessor');
+          }
+        } else {
+          a.outcome = 'review_required';
+          a.reasons.push('deterministic conditions hold; semantic adequacy review required before marking verified (see evidence-strength rubric)');
+        }
+      }
+    }
+    assessments.push(a);
+  }
+
+  let registryDiff = null;
+  if (write) {
+    for (const a of assessments) {
+      const c = registries.claims.entries.find((x) => x.claim_id === a.claim_id);
+      if (a.outcome && a.outcome !== c.status && a.outcome !== 'candidate') {
+        // Never silently upgrade to verified; only downgrades/lateral moves are automated.
+        const upgrade = ['verified', 'verified_narrowed'].includes(a.outcome) && !['verified', 'verified_narrowed'].includes(c.status);
+        if (!upgrade) {
+          c.status = a.outcome;
+          c.provenance = { ...(c.provenance || {}), updated: nowIso(), source: `citable substantiate: ${a.reasons[0]}` };
+        }
+      }
+    }
+    saveRegistry(root, 'claims', registries.claims);
+    registryDiff = diffRegistries(before, registries.claims, 'claim_id');
+  }
+
+  return { assessments, problems, registryDiff };
+}
+
+function requiredInputFor(c) {
+  if (c.claim_type === 'performance') return ['baseline', 'measurement period', 'test population/conditions', 'methodology', 'result source'];
+  if (c.claim_type === 'comparative') return ['comparison set', 'comparison criteria', 'evidence for each compared dimension'];
+  if (c.claim_type === 'security') return ['test report, certification, or architecture evidence'];
+  return ['supporting evidence with an accountable owner'];
+}

package/src/commands/validate.js

@@ -0,0 +1,27 @@
+import { loadRegistries, checkReferentialIntegrity } from '../registries/index.js';
+import { audit } from './audit.js';
+
+/**
+ * `citable validate` — schema-validate all registries plus referential integrity.
+ * `citable validate-claims|validate-evidence|validate-schema|validate-links` narrow to the
+ * relevant detector scope (these require a site target for page-level checks).
+ */
+export async function validate(root, { mode = 'registries', target, baseUrl, refDate } = {}) {
+  const { problems } = loadRegistries(root);
+  const { registries } = loadRegistries(root);
+  const integrity = checkReferentialIntegrity(registries);
+  const structural = [...problems, ...integrity];
+
+  if (mode === 'registries') {
+    return { ok: structural.length === 0, problems: structural, findings: [] };
+  }
+  const scopeMap = { claims: 'claims', evidence: 'evidence', schema: 'schema', links: 'technical', regression: null };
+  const result = await audit(root, { target, scope: scopeMap[mode] ?? undefined, baseUrl, refDate });
+  return {
+    ok: structural.length === 0 && result.findings.filter((f) => ['critical', 'high'].includes(f.classification.severity)).length === 0,
+    problems: structural,
+    findings: result.findings,
+    runId: result.runId,
+    dir: result.dir,
+  };
+}

package/src/crawler/fetch.js

@@ -0,0 +1,31 @@
+/**
+ * Fetch a URL capturing status, headers, body, and redirect chain.
+ * Used only when the operator supplies a deployed target and fetching is permitted.
+ */
+export async function fetchUrl(url, { userAgent = 'CitableAudit/0.1', maxRedirects = 10, timeoutMs = 20000 } = {}) {
+  const chain = [];
+  let current = url;
+  for (let i = 0; i <= maxRedirects; i++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetch(current, {
+        redirect: 'manual',
+        headers: { 'user-agent': userAgent },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const headers = Object.fromEntries(res.headers.entries());
+    if (res.status >= 300 && res.status < 400 && headers.location) {
+      chain.push({ url: current, status: res.status, location: headers.location });
+      current = new URL(headers.location, current).href;
+      continue;
+    }
+    const body = await res.text();
+    return { url: current, requestedUrl: url, status: res.status, headers, body, redirectChain: chain };
+  }
+  throw new Error(`redirect chain exceeded ${maxRedirects} hops for ${url}`);
+}

package/src/crawler/robots.js

@@ -0,0 +1,67 @@
+/** Minimal robots.txt parser sufficient for governance checks. */
+export function parseRobots(text) {
+  const groups = [];
+  let current = null;
+  const sitemaps = [];
+  const errors = [];
+  const lines = String(text ?? '').split(/\r?\n/);
+  lines.forEach((line, i) => {
+    const noComment = line.replace(/#.*$/, '').trim();
+    if (!noComment) return;
+    const m = noComment.match(/^([A-Za-z-]+)\s*:\s*(.*)$/);
+    if (!m) {
+      errors.push(`line ${i + 1}: unparseable: "${line.trim()}"`);
+      return;
+    }
+    const key = m[1].toLowerCase();
+    const value = m[2].trim();
+    if (key === 'user-agent') {
+      if (!current || current.rulesStarted) {
+        current = { agents: [], rules: [], rulesStarted: false };
+        groups.push(current);
+      }
+      current.agents.push(value.toLowerCase());
+    } else if (key === 'allow' || key === 'disallow') {
+      if (!current) {
+        errors.push(`line ${i + 1}: ${key} before any User-agent`);
+        return;
+      }
+      current.rulesStarted = true;
+      current.rules.push({ type: key, path: value });
+    } else if (key === 'sitemap') {
+      sitemaps.push(value);
+    } else if (key === 'crawl-delay') {
+      if (current) { current.rulesStarted = true; current.rules.push({ type: 'crawl-delay', path: value }); }
+    } else {
+      errors.push(`line ${i + 1}: unknown directive "${m[1]}"`);
+    }
+  });
+  return { groups, sitemaps, errors };
+}
+
+function ruleMatches(rulePath, urlPath) {
+  if (rulePath === '') return false; // empty disallow = allow all
+  let re = rulePath.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  if (re.endsWith('\\$')) re = re.slice(0, -2) + '$';
+  return new RegExp('^' + re).test(urlPath);
+}
+
+/** Decide whether userAgent may fetch urlPath under parsed robots. */
+export function isAllowed(parsed, userAgent, urlPath) {
+  const ua = userAgent.toLowerCase();
+  let group =
+    parsed.groups.find((g) => g.agents.some((a) => a !== '*' && ua.includes(a))) ||
+    parsed.groups.find((g) => g.agents.includes('*'));
+  if (!group) return { allowed: true, rule: null };
+  let best = null;
+  for (const r of group.rules) {
+    if (r.type !== 'allow' && r.type !== 'disallow') continue;
+    if (ruleMatches(r.path, urlPath)) {
+      if (!best || r.path.length > best.path.length || (r.path.length === best.path.length && r.type === 'allow')) {
+        best = r;
+      }
+    }
+  }
+  if (!best) return { allowed: true, rule: null };
+  return { allowed: best.type === 'allow', rule: `${best.type}: ${best.path}` };
+}

package/src/crawler/sitemap.js

@@ -0,0 +1,25 @@
+/** Minimal XML sitemap parser (urlset + sitemapindex). */
+export function parseSitemap(xml) {
+  const text = String(xml ?? '');
+  const errors = [];
+  const urls = [];
+  const children = [];
+  const isIndex = /<sitemapindex[\s>]/i.test(text);
+  const blockRe = isIndex ? /<sitemap[\s>]([\s\S]*?)<\/sitemap>/gi : /<url[\s>]([\s\S]*?)<\/url>/gi;
+  let m;
+  while ((m = blockRe.exec(text)) !== null) {
+    const block = m[1];
+    const loc = block.match(/<loc>\s*([\s\S]*?)\s*<\/loc>/i)?.[1]?.trim();
+    const lastmod = block.match(/<lastmod>\s*([\s\S]*?)\s*<\/lastmod>/i)?.[1]?.trim() ?? null;
+    if (!loc) {
+      errors.push('entry missing <loc>');
+      continue;
+    }
+    if (isIndex) children.push({ loc, lastmod });
+    else urls.push({ loc, lastmod });
+  }
+  if (!isIndex && !/<urlset[\s>]/i.test(text) && urls.length === 0) {
+    errors.push('document contains no <urlset> or entries');
+  }
+  return { isIndex, urls, children, errors };
+}

package/src/detectors/ans.js

@@ -0,0 +1,219 @@
+import { defineDetector, indexTargets, registryPageFor, pageSubject } from './framework.js';
+
+const D = [];
+
+const PREAMBLE_RX = /\b(in today'?s (rapidly |ever[- ])?(evolving|changing)|in the (modern|current|digital) (era|age|landscape|world)|now more than ever|as (technology|ai) continues to (evolve|advance)|in an increasingly)\b/i;
+
+D.push(defineDetector({
+  id: 'ANS-001', name: 'Generic preamble before answer', namespace: 'ANS',
+  description: 'The opening paragraph uses generic scene-setting boilerplate instead of answering the page’s question.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: false, requires: ['site'],
+  impact: { citation: 'medium', representation: 'low' },
+  applicable_requirement: 'AEO §4 direct answer block in first 50–100 words; GEO §5 avoid "in today\'s rapidly evolving..." openings; anti-pattern: generic AI introductions',
+  remediation: 'Replace the opening with a direct answer to the principal question in the first 50–100 words.',
+  verification: 'Re-inspect the first paragraph for a direct answer.',
+  check(ctx) {
+    return indexTargets(ctx)
+      .filter((p) => p.status === 200 && p.paragraphs.length > 0 && PREAMBLE_RX.test(p.paragraphs[0]))
+      .map((p) => ({
+        subject: pageSubject(p),
+        summary: 'Opening paragraph is generic preamble, not a direct answer',
+        evidence: [`first paragraph: "${p.paragraphs[0].slice(0, 160)}..."`],
+        confidence: 'high',
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-002', name: 'Question heading without direct answer', namespace: 'ANS',
+  description: 'A heading phrased as a question is not followed by prose before the next heading.',
+  discipline: ['aeo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { citation: 'medium' },
+  applicable_requirement: 'AEO §4 answer extractability; anti-pattern: question headings created only for formatting',
+  remediation: 'Answer the question directly in the text immediately after the heading, or remove the decorative question heading.',
+  verification: 'Confirm prose follows each question heading.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      if (p.status !== 200) continue;
+      const html = p.rawHtml;
+      const rx = /<h([2-4])[^>]*>([^<]*\?)\s*<\/h\1>\s*(<h[1-6]|<\/section|<\/article|<\/body|$)/gi;
+      let m;
+      while ((m = rx.exec(html)) !== null) {
+        hits.push({
+          subject: pageSubject(p),
+          summary: `Question heading "${m[2].trim().slice(0, 80)}" has no answering prose before the next heading`,
+          evidence: [`heading: ${m[2].trim()}`],
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-003', name: 'Circular definition', namespace: 'ANS',
+  description: 'A definitional sentence defines a term using the term itself as the definition head.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: false, requires: ['site'],
+  impact: { citation: 'medium', representation: 'medium' },
+  applicable_requirement: 'AEO §4 explicit definitions; anti-pattern: circular definitions',
+  false_positive_conditions: ['legitimate genus-differentia definitions repeating one word of a compound term'],
+  remediation: 'Rewrite as “[Term] is [genus] that [differentia]”, then state exclusions.',
+  verification: 'Re-inspect the definition sentence.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      if (p.status !== 200) continue;
+      for (const para of p.paragraphs.slice(0, 12)) {
+        const m = para.match(/^([A-Z][A-Za-z0-9 -]{2,60}?)\s+(?:is|are|refers to|means)\s+(.{3,120})/);
+        if (!m) continue;
+        const term = m[1].trim().toLowerCase().replace(/^(the|a|an)\s+/, '');
+        const defHead = m[2].trim().toLowerCase().replace(/^(the|a|an|simply|just|basically)\s+/, '');
+        if (term.split(' ').length >= 2 && defHead.startsWith(term)) {
+          hits.push({
+            subject: pageSubject(p),
+            summary: `Circular definition: "${m[1].trim()}" is defined as itself`,
+            evidence: [`sentence: "${para.slice(0, 160)}"`],
+            confidence: 'high',
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-004', name: 'Deictic dependency in answer text', namespace: 'ANS',
+  description: 'Answer-bearing prose depends on preceding visual context ("as shown above", "in the diagram below"), which breaks when extracted.',
+  discipline: ['aeo'], severity: 'low', deterministic: true, requires: ['site'],
+  impact: { citation: 'medium' },
+  applicable_requirement: 'AEO §4: extracted passage must not distort or lose meaning; GEO §5 decomposable content',
+  remediation: 'Make the passage self-contained: name the referent explicitly instead of pointing at it.',
+  verification: 'Search page text for deictic references.',
+  check(ctx) {
+    const rx = /\b(as (shown|seen|described|illustrated|mentioned) (above|below|earlier|previously)|the (diagram|table|figure|chart|image) (above|below)|see (above|below))\b/i;
+    return indexTargets(ctx)
+      .filter((p) => p.status === 200)
+      .flatMap((p) => {
+        const matches = p.paragraphs.filter((t) => rx.test(t));
+        return matches.length ? [{
+          subject: pageSubject(p),
+          summary: `${matches.length} passage(s) depend on preceding visual context`,
+          evidence: matches.slice(0, 3).map((t) => `"${t.slice(0, 120)}"`),
+        }] : [];
+      });
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-005', name: 'Relative quantity without baseline or timeframe', namespace: 'ANS',
+  description: 'Text asserts a relative numeric improvement ("3x faster", "50% reduction") without a nearby baseline, unit, or timeframe.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: false, requires: ['site'],
+  impact: { citation: 'medium', legal: 'medium', reputational: 'medium' },
+  applicable_requirement: 'AEO §4 atomic factual claims with measurement conditions; detector spec: numerical claim without unit or timeframe; anti-pattern: false precision',
+  false_positive_conditions: ['numbers whose baseline is stated in an adjacent sentence outside the matched window'],
+  remediation: 'State the baseline, measurement period, and test conditions adjacent to the number, or remove the figure.',
+  verification: 'Confirm baseline/conditions appear adjacent to each relative quantity.',
+  check(ctx) {
+    const numRx = /\b(\d+(?:\.\d+)?)\s*(x|times)\s+(faster|slower|better|cheaper|more|fewer|higher|lower)|\b(\d+(?:\.\d+)?)%\s+(reduction|increase|improvement|faster|savings|growth|decrease)/i;
+    const contextRx = /\b(compared (to|with)|versus|vs\.?|baseline|benchmark|measured|test(ed)? (under|conditions|over|during|in)|between \d{4}|in (q[1-4] )?\d{4}|over (a|the) (period|quarter|year|month)|methodology)\b/i;
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      if (p.status !== 200) continue;
+      for (const para of p.paragraphs) {
+        if (numRx.test(para) && !contextRx.test(para)) {
+          hits.push({
+            subject: pageSubject(p),
+            summary: 'Relative quantity asserted without baseline or timeframe in the same passage',
+            evidence: [`passage: "${para.slice(0, 160)}"`],
+            confidence: 'medium',
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-006', name: 'Procedure content without ordered steps', namespace: 'ANS',
+  description: 'A page registered as implementation/how-to content contains no ordered list or numbered steps.',
+  discipline: ['aeo'], severity: 'low', deterministic: true, requires: ['site', 'registries'],
+  impact: { citation: 'medium' },
+  applicable_requirement: 'AEO §4 procedures: provide explicit steps',
+  remediation: 'Express the procedure as explicit ordered steps.',
+  verification: 'Confirm an ordered list or numbered step structure exists.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      const reg = registryPageFor(ctx, p);
+      if (!reg || reg.page_type !== 'implementation' || p.status !== 200) continue;
+      const numbered = /(^|\s)(step\s+\d|1\.\s+\S+[\s\S]{0,400}2\.\s+\S+)/i.test(p.text);
+      if (p.orderedLists === 0 && !numbered) {
+        hits.push({
+          subject: pageSubject(p),
+          summary: `Implementation page ${reg.page_id} has no ordered steps`,
+          evidence: ['0 <ol> elements; no numbered step pattern in text'],
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-007', name: 'Comparison without explicit basis', namespace: 'ANS',
+  description: 'A comparison page has neither a comparison table nor prose stating the comparison criteria.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['site', 'registries'],
+  impact: { citation: 'medium', representation: 'medium' },
+  applicable_requirement: 'AEO §4 comparison tables with prose; detector spec: comparison without explicit comparison basis',
+  remediation: 'State the comparison dimensions explicitly and support them with a table plus prose.',
+  verification: 'Confirm comparison criteria appear in table or prose.',
+  check(ctx) {
+    const basisRx = /\b(differs? (from|in)|difference between|compared (on|across|by)|criteria|dimension|whereas|in contrast|unlike)\b/i;
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      const reg = registryPageFor(ctx, p);
+      if (!reg || reg.page_type !== 'comparison' || p.status !== 200) continue;
+      if (p.tables === 0 && !basisRx.test(p.text)) {
+        hits.push({
+          subject: pageSubject(p),
+          summary: `Comparison page ${reg.page_id} states no explicit comparison basis`,
+          evidence: ['0 tables; no comparison-basis phrasing found in text'],
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-008', name: 'Missing scope or limitations on answer page', namespace: 'ANS',
+  description: 'A definition/comparison/recommendation page never states scope boundaries, exclusions, or limitations.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: false, requires: ['site', 'registries'],
+  impact: { citation: 'medium', legal: 'medium', representation: 'medium' },
+  applicable_requirement: 'AEO §4 boundary conditions; GEO §5 scope boundaries; acceptance standard: limitations disclosed',
+  false_positive_conditions: ['limitations expressed with vocabulary outside the matched set'],
+  remediation: 'Add explicit "when this applies / when it does not / limitations" content.',
+  verification: 'Confirm boundary-condition language exists on the page.',
+  check(ctx) {
+    const rx = /\b(limitation|does not (apply|include|cover|solve|support)|not (intended|suitable|designed) for|out of scope|exclusion|caveat|constraint|boundary condition|when (this|it) (does not|doesn'?t) apply)\b/i;
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      const reg = registryPageFor(ctx, p);
+      if (!reg || !['definition', 'comparison', 'recommendation', 'product'].includes(reg.page_type) || p.status !== 200) continue;
+      if (!rx.test(p.text)) {
+        hits.push({
+          subject: pageSubject(p),
+          summary: `${reg.page_type} page ${reg.page_id} states no scope boundaries or limitations`,
+          evidence: ['no limitation/exclusion/scope-boundary phrasing found in page text'],
+          confidence: 'medium',
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
+export default D;