@nebulacomponents/citable 1.12.0 → 1.13.1

package/src/commands/outcomes.js

@@ -0,0 +1,113 @@
+/**
+ * outcomes command — Customer Outcomes registry
+ *
+ * Enforces the finding_produced → causal_relationship_established
+ * progression and refuses to conflate activity with validated impact.
+ *
+ * Usage:
+ *   citable outcomes list [--stage <stage>]
+ *   citable outcomes show <outcome_id>
+ *   citable outcomes validate
+ *   citable outcomes summary   — stage distribution summary
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+export const OUTCOME_STAGES = [
+  'finding_produced',
+  'finding_accepted',
+  'finding_remediated',
+  'remediation_validated',
+  'search_result_changed',
+  'answer_engine_changed',
+  'commercial_outcome_changed',
+  'causal_relationship_established',
+];
+
+export async function outcomesCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'customer-outcomes.yaml');
+
+  switch (subcommand) {
+    case 'show':     return outcomeShow(file, rest[0]);
+    case 'validate': return outcomeValidate(file);
+    case 'summary':  return outcomeSummary(file);
+    default:         return outcomeList(file, rest);
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'customer-outcomes');
+}
+
+function outcomeList(file, args) {
+  const data = load(file);
+  const stageFilter = args.find((_, i, a) => a[i-1] === '--stage');
+  let entries = stageFilter
+    ? data.entries.filter(e => e.outcome_stage === stageFilter)
+    : data.entries;
+  return {
+    outcomes: entries.map(e => ({
+      outcome_id:          e.outcome_id,
+      customer:            e.customer,
+      property:            e.property,
+      outcome_stage:       e.outcome_stage,
+      causal_confidence:   e.causal_confidence,
+      customer_confirmed:  e.customer_confirmed,
+      independently_verified: e.independently_verified ?? false,
+    })),
+    total: entries.length,
+  };
+}
+
+function outcomeShow(file, id) {
+  if (!id) return { error: 'outcome_id required' };
+  const data = load(file);
+  const o = data.entries.find(e => e.outcome_id === id);
+  if (!o) return { error: `Outcome not found: ${id}` };
+  return { outcome: o };
+}
+
+function outcomeSummary(file) {
+  const data = load(file);
+  const dist = {};
+  for (const s of OUTCOME_STAGES) dist[s] = 0;
+  for (const e of data.entries) dist[e.outcome_stage] = (dist[e.outcome_stage] ?? 0) + 1;
+  const verified = data.entries.filter(e => e.independently_verified).length;
+  const confirmed = data.entries.filter(e => e.customer_confirmed).length;
+  return {
+    stage_distribution: dist,
+    customer_confirmed: confirmed,
+    independently_verified: verified,
+    total: data.entries.length,
+    warning: dist.finding_produced > 0 && dist.causal_relationship_established === 0
+      ? 'All outcomes at finding_produced stage — no causal relationships established yet'
+      : null,
+  };
+}
+
+function outcomeValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('customer-outcome.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const o of data.entries) {
+    // Cannot claim causal confidence without evidence
+    if (['strong','verified'].includes(o.causal_confidence) && (!o.evidence_package || o.evidence_package.length === 0))
+      problems.push(`${o.outcome_id}: causal_confidence "${o.causal_confidence}" requires evidence_package`);
+    // Cannot mark independently_verified without customer_confirmed first
+    if (o.independently_verified && !o.customer_confirmed)
+      problems.push(`${o.outcome_id}: independently_verified=true but customer_confirmed=false`);
+    // Commercial value requires validated stage
+    if (o.commercial_value && !['commercial_outcome_changed','causal_relationship_established'].includes(o.outcome_stage))
+      problems.push(`${o.outcome_id}: commercial_value set but outcome_stage is "${o.outcome_stage}" — commercial value requires commercial_outcome_changed or causal_relationship_established`);
+    // Publication requires confirmation
+    if (o.publication_permission && !o.customer_confirmed)
+      problems.push(`${o.outcome_id}: publication_permission=true but customer_confirmed=false`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/commands/prioritize.js

@@ -0,0 +1,108 @@
+/**
+ * prioritize command — Initiative Prioritization
+ *
+ * Ranks roadmap and investment choices. Weights must be visible when
+ * weighted scoring is used — no opaque scores.
+ *
+ * Usage:
+ *   citable prioritize [--status proposed|approved]
+ *   citable prioritize show <initiative_id>
+ *   citable prioritize validate
+ *   citable prioritize rank   — ranked list with explicit criteria
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+const SCALE = { none: 0, low: 1, medium: 2, high: 3, critical: 4, validated: 4, transformative: 4, trivial: 0, very_high: 4, negligible: 0, 'n/a': 0 };
+
+export async function prioritizeCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'initiatives.yaml');
+
+  switch (subcommand) {
+    case 'show':     return initiativeShow(file, rest[0]);
+    case 'validate': return initiativeValidate(file);
+    case 'rank':     return initiativeRank(file);
+    case 'list':
+    default: {
+      const statusFilter = rest[rest.indexOf('--status') + 1] ?? null;
+      return initiativeList(file, statusFilter);
+    }
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'initiatives');
+}
+
+function initiativeList(file, statusFilter) {
+  const data = load(file);
+  let entries = statusFilter ? data.entries.filter(i => i.status === statusFilter) : data.entries;
+  return {
+    initiatives: entries.map(i => ({
+      initiative_id:             i.initiative_id,
+      title:                     i.title,
+      customer_demand:           i.customer_demand,
+      revenue_potential:         i.revenue_potential,
+      strategic_differentiation: i.strategic_differentiation,
+      evidence_strength:         i.evidence_strength,
+      engineering_cost:          i.engineering_cost,
+      reversibility:             i.reversibility,
+      status:                    i.status,
+      owner:                     i.owner,
+    })),
+    total: entries.length,
+  };
+}
+
+function initiativeShow(file, id) {
+  if (!id) return { error: 'initiative_id required' };
+  const data = load(file);
+  const i = data.entries.find(e => e.initiative_id === id);
+  if (!i) return { error: `Initiative not found: ${id}` };
+  return { initiative: i };
+}
+
+function initiativeRank(file) {
+  const data = load(file);
+  const scorable = data.entries.filter(i => ['proposed','approved'].includes(i.status));
+
+  // Transparent scoring: benefit - cost, with evidence strength as multiplier
+  const scored = scorable.map(i => {
+    const benefit = (SCALE[i.customer_demand] ?? 0) + (SCALE[i.revenue_potential] ?? 0) + (SCALE[i.strategic_differentiation] ?? 0);
+    const cost    = (SCALE[i.engineering_cost] ?? 0) + (SCALE[i.operating_cost ?? 'none'] ?? 0) + (SCALE[i.legal_risk ?? 'none'] ?? 0);
+    const evidenceMultiplier = { assumption: 0.5, anecdote: 0.6, proxy: 0.7, validated: 0.9, verified: 1.0 }[i.evidence_strength] ?? 0.5;
+    const score   = (benefit - cost) * evidenceMultiplier;
+    return { initiative_id: i.initiative_id, title: i.title, score: Math.round(score * 10) / 10, benefit, cost, evidence_strength: i.evidence_strength, reversibility: i.reversibility, evidence_multiplier: evidenceMultiplier };
+  }).sort((a, b) => b.score - a.score);
+
+  return {
+    ranked: scored,
+    scoring_method: 'transparent: (customer_demand + revenue_potential + strategic_differentiation - engineering_cost - operating_cost - legal_risk) × evidence_multiplier',
+    weights: 'equal weights — override with scoring_weights field per initiative if asymmetric weighting is required',
+    total: scored.length,
+  };
+}
+
+function initiativeValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('initiative.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const i of data.entries) {
+    // Evidence strength required
+    if (i.evidence_strength === 'assumption' && i.revenue_potential === 'transformative')
+      problems.push(`${i.initiative_id}: revenue_potential=transformative with evidence_strength=assumption — requires at least "proxy" evidence`);
+    // One-way decisions need justification
+    if (i.reversibility === 'effectively_one_way' && !i.opportunity_cost)
+      problems.push(`${i.initiative_id}: effectively_one_way initiatives require opportunity_cost`);
+    // Platform dependency documented for platform-dependent initiatives
+    if (!i.platform_dependency && /search.console|bing|openai|google|cloudflare/i.test(i.title))
+      problems.push(`${i.initiative_id}: platform_dependency should be documented for platform-dependent initiatives`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/commands/risk.js

@@ -0,0 +1,104 @@
+/**
+ * risk command — Risk Register
+ *
+ * Usage:
+ *   citable risk list [--board]        List all risks (--board: board-visible only)
+ *   citable risk show <risk_id>
+ *   citable risk validate
+ *   citable risk top                   Top risks by residual_exposure
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+import { dateOnly, parseAsOf } from '../shared/asOf.js';
+
+const EXPOSURE_ORDER = ['low','medium','high','critical'];
+
+export async function riskCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'risks.yaml');
+
+  switch (subcommand) {
+    case 'show':     return riskShow(file, rest[0]);
+    case 'validate': return riskValidate(file, parseAsOf(args));
+    case 'top':      return riskTop(file);
+    case 'list':
+    default:
+      return riskList(file, { boardOnly: rest.includes('--board') });
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'risks');
+}
+
+function riskList(file, { boardOnly = false } = {}) {
+  const data = load(file);
+  let entries = boardOnly ? data.entries.filter(r => r.board_visibility) : data.entries;
+  return {
+    risks: entries.map(r => ({
+      risk_id:          r.risk_id,
+      title:            r.title,
+      category:         r.category,
+      gross_exposure:   r.gross_exposure,
+      residual_exposure:r.residual_exposure,
+      trend:            r.trend,
+      review_date:      r.review_date,
+      board_visibility: r.board_visibility,
+    })),
+    total: entries.length,
+  };
+}
+
+function riskShow(file, id) {
+  if (!id) return { error: 'risk_id required' };
+  const data = load(file);
+  const r = data.entries.find(e => e.risk_id === id);
+  if (!r) return { error: `Risk not found: ${id}` };
+  return { risk: r };
+}
+
+function riskTop(file) {
+  const data = load(file);
+  const sorted = [...data.entries].sort((a, b) =>
+    EXPOSURE_ORDER.indexOf(b.residual_exposure) - EXPOSURE_ORDER.indexOf(a.residual_exposure)
+  );
+  return {
+    top_risks: sorted.slice(0, 10).map(r => ({
+      risk_id:           r.risk_id,
+      title:             r.title,
+      category:          r.category,
+      residual_exposure: r.residual_exposure,
+      trend:             r.trend,
+      control_effectiveness: r.control_effectiveness,
+      trigger_threshold: r.trigger_threshold,
+      response_owner:    r.response_owner,
+    })),
+  };
+}
+
+function riskValidate(file, asOf) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('risk.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const r of data.entries) {
+    // KRIs required for critical/high risks
+    if (['high','critical'].includes(r.residual_exposure) && (!r.key_risk_indicators || r.key_risk_indicators.length === 0))
+      problems.push(`${r.risk_id}: high/critical residual_exposure requires key_risk_indicators`);
+    // Trigger threshold required for board-visible risks
+    if (r.board_visibility && !r.trigger_threshold)
+      problems.push(`${r.risk_id}: board_visibility=true requires trigger_threshold`);
+    // Stale review dates
+    const reviewDate = r.review_date ? new Date(r.review_date) : null;
+    if (reviewDate && reviewDate < asOf)
+      problems.push(`${r.risk_id}: review_date ${r.review_date} is in the past — risk review overdue`);
+    // Controls effectiveness vs gross/residual mismatch
+    if (r.gross_exposure === 'critical' && r.control_effectiveness === 'none' && r.residual_exposure !== 'critical')
+      problems.push(`${r.risk_id}: control_effectiveness=none but residual_exposure < gross_exposure — inconsistent`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length, as_of: dateOnly(asOf) };
+}

package/src/commands/scenario.js

@@ -0,0 +1,98 @@
+/**
+ * scenario command — Scenario War Room
+ *
+ * Models compound risks with cascade analysis and early-warning triggers.
+ * Maximum 3 variables per scenario. Requires explicit hedges with cost,
+ * impact, owner, and deadline — not just worst-case narratives.
+ *
+ * Usage:
+ *   citable scenario list
+ *   citable scenario show <scenario_id>
+ *   citable scenario validate
+ *   citable scenario triggers   — early-warning trigger summary
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+export async function scenarioCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'scenarios.yaml');
+
+  switch (subcommand) {
+    case 'show':     return scenarioShow(file, rest[0]);
+    case 'validate': return scenarioValidate(file);
+    case 'triggers': return scenarioTriggers(file);
+    default:         return scenarioList(file);
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'scenarios');
+}
+
+function scenarioList(file) {
+  const data = load(file);
+  return {
+    scenarios: data.entries.map(s => ({
+      scenario_id: s.scenario_id,
+      title: s.title,
+      variables: (s.variables ?? []).length,
+      cascade_steps: (s.cascade_analysis ?? []).length,
+      hedges: (s.hedges ?? []).length,
+      early_warnings: (s.early_warning_triggers ?? []).length,
+      owner: s.owner,
+    })),
+    total: data.entries.length,
+  };
+}
+
+function scenarioShow(file, id) {
+  if (!id) return { error: 'scenario_id required' };
+  const data = load(file);
+  const s = data.entries.find(e => e.scenario_id === id);
+  if (!s) return { error: `Scenario not found: ${id}` };
+  return { scenario: s };
+}
+
+function scenarioTriggers(file) {
+  const data = load(file);
+  return {
+    triggers: data.entries.flatMap(s =>
+      (s.early_warning_triggers ?? []).map(t => ({
+        scenario_id: s.scenario_id, title: s.title, trigger: t,
+      }))
+    ),
+    total_scenarios: data.entries.length,
+  };
+}
+
+function scenarioValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('scenario.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const s of data.entries) {
+    // Variables capped at 3
+    if ((s.variables ?? []).length > 3)
+      problems.push(`${s.scenario_id}: maximum 3 variables per scenario — combine compound drivers into a single variable`);
+    // Cascade analysis required (not just isolated risk statements)
+    if (!s.cascade_analysis || s.cascade_analysis.length === 0)
+      problems.push(`${s.scenario_id}: cascade_analysis required — scenarios must show cascading effects, not isolated risks`);
+    // All three states required
+    if (!s.states?.base || !s.states?.stress || !s.states?.severe)
+      problems.push(`${s.scenario_id}: all three states (base, stress, severe) required`);
+    // Hedges must have all required fields
+    for (const h of s.hedges ?? []) {
+      if (!h.cost || !h.impact || !h.owner || !h.deadline)
+        problems.push(`${s.scenario_id} hedge "${h.action}": cost, impact, owner, and deadline all required`);
+    }
+    // Early-warning triggers required
+    if (!s.early_warning_triggers || s.early_warning_triggers.length === 0)
+      problems.push(`${s.scenario_id}: early_warning_triggers required — scenario without triggers is a narrative, not a management tool`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/commands/variance.js

@@ -0,0 +1,102 @@
+/**
+ * variance command — Variance analysis registry
+ *
+ * Rejects non-causes (market conditions, timing, customer behaviour)
+ * unless decomposed into specific observed mechanisms.
+ *
+ * Usage:
+ *   citable variance list [--period <period>]
+ *   citable variance show <variance_id>
+ *   citable variance validate
+ *   citable variance material   — list material/critical variances only
+ */
+import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+
+
+// Vague causes that must be decomposed before acceptance
+const REJECTED_CAUSE_PATTERNS = [
+  /^market conditions?$/i,
+  /^timing$/i,
+  /^customer behaviour?$/i,
+  /^execution issues?$/i,
+  /^macro(economic)?$/i,
+  /^seasonality$/i,
+];
+
+export async function varianceCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const file = path.join(contextDir(root), 'variances.yaml');
+
+  switch (subcommand) {
+    case 'show':     return varianceShow(file, rest[0]);
+    case 'validate': return varianceValidate(file);
+    case 'material': return varianceList(file, { materialOnly: true });
+    default: {
+      const i = rest.indexOf('--period');
+      return varianceList(file, { period: i >= 0 ? rest[i + 1] : null });
+    }
+  }
+}
+
+function load(file) {
+  return loadRegistryFile(file, 'variances');
+}
+
+function varianceList(file, { materialOnly = false, period = null } = {}) {
+  const data = load(file);
+  let entries = data.entries;
+  if (materialOnly) entries = entries.filter(v => ['material','critical'].includes(v.materiality));
+  if (period) entries = entries.filter(v => v.period === period);
+  return {
+    variances: entries.map(v => ({
+      variance_id:    v.variance_id,
+      metric_id:      v.metric_id,
+      period:         v.period,
+      variance_pct:   v.variance_pct,
+      materiality:    v.materiality,
+      primary_driver: v.primary_driver,
+      controllable:   v.controllable,
+      confidence:     v.confidence,
+    })),
+    total: entries.length,
+  };
+}
+
+function varianceShow(file, id) {
+  if (!id) return { error: 'variance_id required' };
+  const data = load(file);
+  const v = data.entries.find(e => e.variance_id === id);
+  if (!v) return { error: `Variance not found: ${id}` };
+  return { variance: v };
+}
+
+function varianceValidate(file) {
+  const data = load(file);
+  const problems = [...registryLoadProblems(data)];
+  const { valid, errors } = validateAgainst('variance.schema.json', data);
+  if (!valid) problems.push(...errors);
+
+  for (const v of data.entries) {
+    // Reject vague causes
+    for (const pattern of REJECTED_CAUSE_PATTERNS) {
+      if (pattern.test((v.primary_driver ?? '').trim())) {
+        problems.push(`${v.variance_id}: primary_driver "${v.primary_driver}" is a non-cause — decompose into a specific observed mechanism`);
+      }
+      for (const d of v.secondary_drivers ?? []) {
+        if (pattern.test(d.trim())) {
+          problems.push(`${v.variance_id}: secondary_driver "${d}" is a non-cause — decompose into a specific observed mechanism`);
+        }
+      }
+    }
+    // Material variances need management response
+    if (['material','critical'].includes(v.materiality) && !v.management_response)
+      problems.push(`${v.variance_id}: material variance requires management_response`);
+    // Evidence required
+    if (!v.evidence || v.evidence.length === 0)
+      problems.push(`${v.variance_id}: evidence array must not be empty`);
+  }
+
+  return { valid: problems.length === 0, problems, checked: data.entries.length };
+}

package/src/detectors/framework.js

@@ -100,12 +100,49 @@ export function runDetectors(detectors, ctx) {
 /** Pages whose declared or default intent is to be indexed. */
 export function indexTargets(ctx) {
   return ctx.site.pages.filter((p) => {
+    if (isProviderUtilityUrl(p.url)) return false;
     const reg = registryPageFor(ctx, p);
     if (reg?.indexing_intent === 'noindex') return false;
     return true;
   });
 }
 
+/** Index targets whose response is an HTML document. */
+export function htmlIndexTargets(ctx) {
+  return indexTargets(ctx).filter(isHtmlDocument);
+}
+
+export function isHtmlDocument(page) {
+  const type = String(page?.contentType || '').toLowerCase();
+  return !type || type.includes('text/html') || type.includes('application/xhtml+xml');
+}
+
+/** URLs that conventionally identify HTML documents rather than media/data resources. */
+export function isHtmlDocumentUrl(url) {
+  try {
+    const pathname = new URL(url).pathname;
+    const name = pathname.split('/').pop() || '';
+    const match = name.match(/\.([a-z0-9]+)$/i);
+    return Boolean(match) && ['html', 'htm', 'xhtml'].includes(match[1].toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function hasHtmlDocumentMarkup(page) {
+  return /^\s*(?:<!doctype\s+html\b|<html\b)/i.test(String(page?.rawHtml || ''));
+}
+
+/** Provider-owned utility routes are link evidence, not default content pages. */
+export function isProviderUtilityUrl(url) {
+  try {
+    const { pathname } = new URL(url);
+    return pathname === '/cdn-cgi' || pathname.startsWith('/cdn-cgi/');
+  } catch {
+    return false;
+  }
+}
+
 /** Match a live page to its registry entry by URL path. */
 export function registryPageFor(ctx, page) {
   const entries = ctx.registries?.pages?.entries || [];

package/src/detectors/page.js

@@ -1,4 +1,4 @@
-import { defineDetector, indexTargets, pageSubject } from './framework.js';
+import { defineDetector, htmlIndexTargets, pageSubject } from './framework.js';
 
 const D = [];
 
@@ -11,7 +11,7 @@ D.push(defineDetector({
   remediation: 'Add a concise title identifying the page subject and distinguishing it from other pages.',
   verification: 'Confirm a non-empty <title> in rendered HTML.',
   check(ctx) {
-    return indexTargets(ctx).filter((p) => p.status === 200 && !p.title).map((p) => ({
+    return htmlIndexTargets(ctx).filter((p) => p.status === 200 && !p.title).map((p) => ({
       subject: pageSubject(p), summary: 'Page has no title element', evidence: ['<title> absent or empty'],
     }));
   },
@@ -27,7 +27,7 @@ D.push(defineDetector({
   verification: 'Confirm title uniqueness across index targets.',
   check(ctx) {
     const byTitle = new Map();
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (!p.title || p.status !== 200) continue;
       if (!byTitle.has(p.title)) byTitle.set(p.title, []);
       byTitle.get(p.title).push(p);
@@ -49,7 +49,7 @@ D.push(defineDetector({
   remediation: 'Add an accurate, page-specific description stating the expected value.',
   verification: 'Confirm meta[name=description] present and non-empty.',
   check(ctx) {
-    return indexTargets(ctx).filter((p) => p.status === 200 && !p.metaDescription).map((p) => ({
+    return htmlIndexTargets(ctx).filter((p) => p.status === 200 && !p.metaDescription).map((p) => ({
       subject: pageSubject(p), summary: 'Page has no meta description', evidence: ['meta[name=description] absent'],
     }));
   },
@@ -65,7 +65,7 @@ D.push(defineDetector({
   verification: 'Confirm description uniqueness.',
   check(ctx) {
     const byDesc = new Map();
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (!p.metaDescription || p.status !== 200) continue;
       if (!byDesc.has(p.metaDescription)) byDesc.set(p.metaDescription, []);
       byDesc.get(p.metaDescription).push(p);
@@ -87,7 +87,7 @@ D.push(defineDetector({
   remediation: 'Use exactly one H1 that identifies the page purpose.',
   verification: 'Count H1 elements.',
   check(ctx) {
-    return indexTargets(ctx).filter((p) => p.status === 200 && p.h1s.length !== 1).map((p) => ({
+    return htmlIndexTargets(ctx).filter((p) => p.status === 200 && p.h1s.length !== 1).map((p) => ({
       subject: pageSubject(p),
       summary: p.h1s.length === 0 ? 'Page has no H1' : `Page has ${p.h1s.length} H1 elements`,
       evidence: p.h1s.length ? p.h1s.map((h) => `H1: ${h.text}`) : ['no <h1> found'],
@@ -106,7 +106,7 @@ D.push(defineDetector({
   verification: 'Walk heading sequence and confirm no level is skipped.',
   check(ctx) {
     const hits = [];
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (p.status !== 200) continue;
       let prev = 0;
       for (const h of p.headings) {
@@ -134,7 +134,7 @@ D.push(defineDetector({
   remediation: 'Add descriptive alt text (or empty alt for purely decorative images, reviewed case by case).',
   verification: 'Confirm every <img> has an alt attribute.',
   check(ctx) {
-    return indexTargets(ctx)
+    return htmlIndexTargets(ctx)
       .map((p) => ({ p, missing: p.images.filter((i) => i.alt === undefined || i.alt === null) }))
       .filter(({ p, missing }) => p.status === 200 && missing.length > 0)
       .map(({ p, missing }) => ({
@@ -156,7 +156,7 @@ D.push(defineDetector({
   verification: 'Re-measure extracted word count after revision.',
   check(ctx) {
     const min = ctx.config?.audit?.thin_content_words ?? 120;
-    return indexTargets(ctx)
+    return htmlIndexTargets(ctx)
       .filter((p) => p.status === 200 && p.wordCount > 0 && p.wordCount < min)
       .map((p) => ({
         subject: pageSubject(p),
@@ -178,7 +178,7 @@ D.push(defineDetector({
   verification: 'Re-measure dominant-term density.',
   check(ctx) {
     const hits = [];
-    for (const p of indexTargets(ctx)) {
+    for (const p of htmlIndexTargets(ctx)) {
       if (p.status !== 200 || p.wordCount < 80) continue;
       const words = p.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || [];
       const freq = new Map();