@nebulacomponents/citable 1.13.1 → 1.15.0

package/src/commands/reportShareOfVoice.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  calculateShareOfVoice,
+  extractDomain,
+  loadCitationRuns,
+  renderShareOfVoiceHtml,
+  renderShareOfVoiceMarkdown,
+} from '../reporting/shareOfVoice.js';
+import { loadRegistries } from '../registries/index.js';
+
+/**
+ * `citable report share-of-voice` — compute first-party and competitor citation share
+ * across recorded observation runs. Never invents competitor citations; unevidenced
+ * prompts and competitors are reported plainly.
+ */
+export function reportShareOfVoice(root, { since, last } = {}) {
+  if (last != null && (!Number.isInteger(last) || last < 1)) {
+    throw new Error('--last must be a positive integer');
+  }
+
+  const { registries } = loadRegistries(root);
+  const competitors = registries.competitors?.entries || [];
+
+  const firstPartyDomains = new Set();
+  if (registries.config?.site?.base_url) {
+    const d = extractDomain(registries.config.site.base_url);
+    if (d) firstPartyDomains.add(d);
+  }
+  if (registries.pages?.entries) {
+    for (const p of registries.pages.entries) {
+      if (p.url) {
+        const d = extractDomain(p.url);
+        if (d) firstPartyDomains.add(d);
+      }
+    }
+  }
+
+  const { included, skipped } = loadCitationRuns(root, { since, last });
+  const data = calculateShareOfVoice(included, competitors, firstPartyDomains);
+
+  const dir = path.join(root, '.citable', 'reports');
+  const pathMd = path.join(dir, 'share-of-voice.md');
+  const pathHtml = path.join(dir, 'share-of-voice.html');
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(pathMd, renderShareOfVoiceMarkdown(data, skipped));
+  fs.writeFileSync(pathHtml, renderShareOfVoiceHtml(data, skipped));
+
+  return {
+    dir,
+    included: included.length,
+    skipped: skipped.length,
+    competitors_evaluated: competitors.length,
+    prompts_evaluated: data.prompts.length,
+    total_citations: data.total_citations_recorded,
+    path_md: pathMd,
+    path_html: pathHtml,
+  };
+}

package/src/commands/schemaCmd.js

@@ -1,6 +1,7 @@
 import { buildContext } from './context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, sitePageFor } from '../detectors/framework.js';
+import { checklistItem, toStringArray } from '../shared/checklist.js';
 
 /**
  * `citable schema` — derive JSON-LD proposals from registry data and validate deployed schema.
@@ -28,7 +29,10 @@ export async function schemaCommand(root, { target, baseUrl, refDate } = {}) {
     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 });
+      blocked.push({
+        entity_id: e.entity_id, status: 'blocked', reason: 'entity record incomplete; schema would require invented facts',
+        required_input: toStringArray(missing.map((field) => checklistItem(field, field))),
+      });
       continue;
     }
     const id = `${e.canonical_url}#${e.entity_type}`;

package/src/commands/substantiate.js

@@ -1,5 +1,6 @@
 import { loadRegistries, saveRegistry, diffRegistries } from '../registries/index.js';
 import { isPastDate, nowIso, parseRefDate } from '../shared/io.js';
+import { checklistItem, toStringArray } from '../shared/checklist.js';
 
 const REGULATED = new Set(['legal_regulatory', 'security', 'commercial']);
 
@@ -37,7 +38,7 @@ export function substantiate(root, { write = false, refDate } = {}) {
     } 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');
+      a.required_input.push(checklistItem('legal-review', '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';
@@ -54,19 +55,23 @@ export function substantiate(root, { write = false, refDate } = {}) {
       } 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');
+        a.required_input.push(checklistItem('current-verified-evidence', '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)');
+        a.required_input.push(checklistItem('primary-evidence', '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');
+        a.required_input.push(
+          checklistItem('methodology', 'methodology'),
+          checklistItem('test-conditions', 'test conditions'),
+          checklistItem('measurement-period', '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');
+        a.required_input.push(checklistItem('scope-exclusions', 'explicit scope and exclusions'));
       } else {
         // Deterministic conditions passed. Verified status additionally requires a recorded
         // semantic support assessment (entailment) by a named assessor — evidence linkage
@@ -82,7 +87,7 @@ export function substantiate(root, { write = false, refDate } = {}) {
           } 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');
+            a.required_input.push(checklistItem('support-assessment', 'support_assessment with named assessor'));
           }
         } else {
           a.outcome = 'review_required';
@@ -90,6 +95,7 @@ export function substantiate(root, { write = false, refDate } = {}) {
         }
       }
     }
+    a.required_input = toStringArray(a.required_input);
     assessments.push(a);
   }
 
@@ -114,8 +120,14 @@ export function substantiate(root, { write = false, refDate } = {}) {
 }
 
 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'];
+  if (c.claim_type === 'performance') {
+    return ['baseline', 'measurement period', 'test population/conditions', 'methodology', 'result source']
+      .map((label) => checklistItem(label.replace(/[^a-z0-9]+/gi, '-').toLowerCase(), label));
+  }
+  if (c.claim_type === 'comparative') {
+    return ['comparison set', 'comparison criteria', 'evidence for each compared dimension']
+      .map((label) => checklistItem(label.replace(/[^a-z0-9]+/gi, '-').toLowerCase(), label));
+  }
+  if (c.claim_type === 'security') return [checklistItem('security-evidence', 'test report, certification, or architecture evidence')];
+  return [checklistItem('owned-evidence', 'supporting evidence with an accountable owner')];
 }

package/src/connectors/http.js

@@ -1,15 +1,18 @@
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 
-export async function providerRequest(url, { token, fetchImpl = globalThis.fetch, method = 'GET', body, attempts = 3 } = {}) {
+export async function providerRequest(url, { token, fetchImpl = globalThis.fetch, method = 'GET', body, headers = {}, attempts = 3, rawResponse = false } = {}) {
   if (!token) throw Object.assign(new Error('authorization is not configured'), { connectorState: 'not_configured' });
   let response;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     response = await fetchImpl(url, {
       method,
-      headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+      headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}), ...headers },
       body: body ? JSON.stringify(body) : undefined,
     });
-    if (response.ok) return response.json();
+    if (response.ok) {
+      if (rawResponse) return response;
+      return response.json();
+    }
     const detail = (await response.text()).slice(0, 300);
     if (!RETRYABLE.has(response.status) || attempt === attempts) {
       const states = { 401: 'authorization_expired', 403: 'permission_denied', 429: 'quota_limited' };

package/src/connectors/index.js

@@ -1,7 +1,9 @@
 import { gscConnector } from './gsc.js';
 import { ga4Connector } from './ga4.js';
+import { wordpressConnector } from './wordpress.js';
+import { webflowConnector } from './webflow.js';
 
-const CONNECTORS = new Map([gscConnector, ga4Connector].map((connector) => [connector.provider, connector]));
+const CONNECTORS = new Map([gscConnector, ga4Connector, wordpressConnector, webflowConnector].map((connector) => [connector.provider, connector]));
 
 export function getConnector(provider) {
   const connector = CONNECTORS.get(String(provider).toLowerCase());

package/src/connectors/webflow.js

@@ -0,0 +1,224 @@
+import { providerRequest } from './http.js';
+import { sha256, nowIso } from '../shared/io.js';
+
+const BASE = 'https://api.webflow.com/v2';
+
+const METRICS = {
+  pages: { unit: 'count', value_type: 'integer' },
+  collections: { unit: 'count', value_type: 'integer' },
+  items: { unit: 'count', value_type: 'integer' },
+};
+
+function computeWebflowPayloadHash(payload) {
+  const canonical = {
+    target_id: String(payload.target_id || payload.id),
+    site_id: String(payload.site_id || ''),
+    title: String(payload.title || ''),
+    slug: String(payload.slug || ''),
+    meta_title: String(payload.meta_title || ''),
+    meta_description: String(payload.meta_description || ''),
+    open_graph_title: String(payload.open_graph_title || ''),
+    open_graph_description: String(payload.open_graph_description || ''),
+    body: String(payload.body || ''),
+  };
+  return sha256(JSON.stringify(canonical));
+}
+
+export const webflowConnector = {
+  provider: 'webflow',
+  defaultCredentialEnv: 'WEBFLOW_API_TOKEN',
+  readOnlyScopes: ['sites:read', 'pages:read', 'cms:read'],
+  writeScopes: ['pages:write', 'cms:write'],
+
+  describeMetrics() {
+    return METRICS;
+  },
+
+  async discoverProperties(context) {
+    const result = await providerRequest(`${BASE}/sites`, context);
+    const sites = result.sites || [];
+    return sites.map((site) => ({
+      property_id: site.id,
+      display_name: site.displayName || site.id,
+      custom_domains: (site.customDomains || []).map((d) => d.url || d.host || d),
+      time_zone: site.timeZone || null,
+      created_on: site.createdOn || null,
+      permission: 'administrator',
+    }));
+  },
+
+  async validateConnection(connection, context) {
+    const site = await providerRequest(`${BASE}/sites/${encodeURIComponent(connection.property_id)}`, context);
+    const valid = Boolean(site && site.id === connection.property_id);
+    return {
+      valid,
+      site_id: site?.id || connection.property_id,
+      display_name: site?.displayName || null,
+      last_published: site?.lastPublished || null,
+    };
+  },
+
+  async sync(connection, metrics, { startDate, endDate, ...context }) {
+    const siteId = connection.property_id;
+    const rows = [];
+    const metricNames = new Set(metrics.map((m) => m.external_name));
+
+    if (metricNames.has('pages')) {
+      const pageResult = await providerRequest(`${BASE}/sites/${encodeURIComponent(siteId)}/pages`, context);
+      const pages = pageResult.pages || [];
+      const pageMetric = metrics.find((m) => m.external_name === 'pages');
+      rows.push({
+        metric: pageMetric,
+        value: pages.length,
+        dimensions: { date: endDate },
+        observed_at: `${endDate}T00:00:00.000Z`,
+      });
+    }
+
+    if (metricNames.has('collections') || metricNames.has('items')) {
+      const collectionsResult = await providerRequest(`${BASE}/sites/${encodeURIComponent(siteId)}/collections`, context);
+      const collections = collectionsResult.collections || [];
+
+      if (metricNames.has('collections')) {
+        const colMetric = metrics.find((m) => m.external_name === 'collections');
+        rows.push({
+          metric: colMetric,
+          value: collections.length,
+          dimensions: { date: endDate },
+          observed_at: `${endDate}T00:00:00.000Z`,
+        });
+      }
+
+      if (metricNames.has('items')) {
+        let totalItems = 0;
+        for (const col of collections) {
+          const itemsResult = await providerRequest(`${BASE}/collections/${encodeURIComponent(col.id)}/items?limit=100`, context);
+          totalItems += (itemsResult.items || []).length;
+        }
+        const itemMetric = metrics.find((m) => m.external_name === 'items');
+        rows.push({
+          metric: itemMetric,
+          value: totalItems,
+          dimensions: { date: endDate },
+          observed_at: `${endDate}T00:00:00.000Z`,
+        });
+      }
+    }
+
+    return {
+      rows,
+      cursor: endDate,
+      limitations: [
+        'Webflow API enforces rate limits of 60 requests per minute.',
+        'Staged CMS changes require site publish to appear on live domains.',
+      ],
+    };
+  },
+
+  /**
+   * Read Webflow page or collection item content and SEO metadata with hash integrity.
+   */
+  async readContent(connection, targetId, context) {
+    if (!targetId) throw new Error('Webflow readContent requires targetId');
+    const page = await providerRequest(`${BASE}/pages/${encodeURIComponent(targetId)}`, context);
+
+    const payload = {
+      target_id: String(page.id),
+      site_id: page.siteId || connection.property_id,
+      title: page.title || '',
+      slug: page.slug || '',
+      meta_title: page.seo?.title || page.title || '',
+      meta_description: page.seo?.description || '',
+      open_graph_title: page.openGraph?.title || null,
+      open_graph_description: page.openGraph?.description || null,
+      body: page.body || '',
+      draft: Boolean(page.draft),
+      archived: Boolean(page.archived),
+      published: Boolean(page.published),
+    };
+
+    const contentHash = computeWebflowPayloadHash(payload);
+    return { ...payload, content_hash: contentHash };
+  },
+
+  /**
+   * Apply reviewed, hash-locked remediation to a Webflow page.
+   */
+  async applyRemediation(connection, remediation, context = {}) {
+    if (!remediation.reviewer) {
+      throw new Error('CMS remediation requires a named human reviewer per governance rules');
+    }
+    if (!remediation.expected_hash) {
+      throw new Error('CMS remediation requires expected_hash for hash-locking');
+    }
+    if (!remediation.target_id) {
+      throw new Error('CMS remediation requires target_id');
+    }
+
+    const current = await this.readContent(connection, remediation.target_id, context);
+    if (current.content_hash !== remediation.expected_hash) {
+      throw new Error(`stale remediation refused for Webflow ${remediation.target_id}: content hash changed (${current.content_hash} !== ${remediation.expected_hash})`);
+    }
+
+    const updates = remediation.updates || {};
+    const candidatePayload = {
+      ...current,
+      title: updates.title !== undefined ? updates.title : current.title,
+      slug: updates.slug !== undefined ? updates.slug : current.slug,
+      meta_title: updates.meta_title !== undefined ? updates.meta_title : current.meta_title,
+      meta_description: updates.meta_description !== undefined ? updates.meta_description : current.meta_description,
+      open_graph_title: updates.open_graph_title !== undefined ? updates.open_graph_title : current.open_graph_title,
+      open_graph_description: updates.open_graph_description !== undefined ? updates.open_graph_description : current.open_graph_description,
+      body: updates.body !== undefined ? updates.body : current.body,
+    };
+    const simulatedHash = computeWebflowPayloadHash(candidatePayload);
+
+    // Dry-run mode by default
+    if (!context.write) {
+      return {
+        status: 'proposed',
+        dry_run: true,
+        target_id: remediation.target_id,
+        before_hash: current.content_hash,
+        after_hash: simulatedHash,
+        updates,
+        reviewer: remediation.reviewer,
+      };
+    }
+
+    // Live update via PATCH
+    const body = {};
+    if (updates.title !== undefined) body.title = updates.title;
+    if (updates.slug !== undefined) body.slug = updates.slug;
+    if (updates.body !== undefined) body.body = updates.body;
+    if (updates.meta_title !== undefined || updates.meta_description !== undefined) {
+      body.seo = {
+        title: updates.meta_title !== undefined ? updates.meta_title : current.meta_title,
+        description: updates.meta_description !== undefined ? updates.meta_description : current.meta_description,
+      };
+    }
+    if (updates.open_graph_title !== undefined || updates.open_graph_description !== undefined) {
+      body.openGraph = {
+        title: updates.open_graph_title !== undefined ? updates.open_graph_title : current.open_graph_title,
+        description: updates.open_graph_description !== undefined ? updates.open_graph_description : current.open_graph_description,
+      };
+    }
+
+    await providerRequest(`${BASE}/pages/${encodeURIComponent(remediation.target_id)}`, {
+      ...context,
+      method: 'PATCH',
+      body,
+    });
+
+    const updated = await this.readContent(connection, remediation.target_id, context);
+    return {
+      status: 'applied',
+      dry_run: false,
+      target_id: remediation.target_id,
+      before_hash: current.content_hash,
+      after_hash: updated.content_hash,
+      updated_at: nowIso(),
+      reviewer: remediation.reviewer,
+    };
+  },
+};

package/src/connectors/wordpress.js

@@ -0,0 +1,226 @@
+import { providerRequest } from './http.js';
+import { sha256, nowIso } from '../shared/io.js';
+
+const METRICS = {
+  published_posts: { unit: 'count', value_type: 'integer' },
+  published_pages: { unit: 'count', value_type: 'integer' },
+};
+
+function normalizeBaseUrl(propertyId) {
+  if (!propertyId) throw new Error('WordPress property_id must be the base site or API URL');
+  return String(propertyId).replace(/\/+$/, '');
+}
+
+function computeCmsPayloadHash(payload) {
+  const canonical = {
+    target_id: String(payload.target_id || payload.id),
+    title: String(payload.title || ''),
+    content: String(payload.content || ''),
+    excerpt: String(payload.excerpt || ''),
+    slug: String(payload.slug || ''),
+    status: String(payload.status || 'publish'),
+    meta: payload.meta || {},
+    schema_data: payload.schema_data || null,
+  };
+  return sha256(JSON.stringify(canonical));
+}
+
+export const wordpressConnector = {
+  provider: 'wordpress',
+  defaultCredentialEnv: 'WORDPRESS_AUTH_TOKEN',
+  readOnlyScopes: [
+    'https://api.wordpress.org/auth/posts.readonly',
+    'https://api.wordpress.org/auth/pages.readonly',
+  ],
+  writeScopes: [
+    'https://api.wordpress.org/auth/posts.edit',
+    'https://api.wordpress.org/auth/pages.edit',
+  ],
+
+  describeMetrics() {
+    return METRICS;
+  },
+
+  async discoverProperties(context) {
+    const targetUrl = context.property_id || context.siteUrl || context.url;
+    if (!targetUrl) {
+      return [{
+        property_id: 'https://example.test',
+        display_name: 'WordPress Site (configure with site URL)',
+        permission: 'administrator',
+      }];
+    }
+    const base = normalizeBaseUrl(targetUrl);
+    const siteInfo = await providerRequest(`${base}/wp-json`, context);
+    return [{
+      property_id: siteInfo.url || base,
+      display_name: siteInfo.name || base,
+      description: siteInfo.description || null,
+      home: siteInfo.home || null,
+      permission: 'administrator',
+    }];
+  },
+
+  async validateConnection(connection, context) {
+    const base = normalizeBaseUrl(connection.property_id);
+    const user = await providerRequest(`${base}/wp-json/wp/v2/users/me?context=edit`, context);
+    const valid = Boolean(user && (user.id || user.name));
+    return {
+      valid,
+      user: user?.name || null,
+      roles: user?.roles || [],
+      capabilities: user?.capabilities || {},
+    };
+  },
+
+  async sync(connection, metrics, { startDate, endDate, ...context }) {
+    const base = normalizeBaseUrl(connection.property_id);
+    const rows = [];
+    const metricNames = new Set(metrics.map((m) => m.external_name));
+
+    if (metricNames.has('published_posts')) {
+      const posts = await providerRequest(`${base}/wp-json/wp/v2/posts?per_page=100&status=publish`, context);
+      const postMetric = metrics.find((m) => m.external_name === 'published_posts');
+      rows.push({
+        metric: postMetric,
+        value: Array.isArray(posts) ? posts.length : 0,
+        dimensions: { date: endDate },
+        observed_at: `${endDate}T00:00:00.000Z`,
+      });
+    }
+
+    if (metricNames.has('published_pages')) {
+      const pages = await providerRequest(`${base}/wp-json/wp/v2/pages?per_page=100&status=publish`, context);
+      const pageMetric = metrics.find((m) => m.external_name === 'published_pages');
+      rows.push({
+        metric: pageMetric,
+        value: Array.isArray(pages) ? pages.length : 0,
+        dimensions: { date: endDate },
+        observed_at: `${endDate}T00:00:00.000Z`,
+      });
+    }
+
+    return {
+      rows,
+      cursor: endDate,
+      limitations: [
+        'WordPress REST API collection is bounded to accessible posts and pages.',
+        'Custom post types outside standard posts and pages require dedicated endpoint parameters.',
+      ],
+    };
+  },
+
+  /**
+   * Read CMS page/post content, metadata, and structured data with hash integrity.
+   */
+  async readContent(connection, targetId, context) {
+    if (!targetId) throw new Error('WordPress readContent requires targetId');
+    const base = normalizeBaseUrl(connection.property_id);
+    let item;
+    try {
+      item = await providerRequest(`${base}/wp-json/wp/v2/pages/${encodeURIComponent(targetId)}?context=edit`, context);
+    } catch {
+      // Fall back to posts if not a page
+      item = await providerRequest(`${base}/wp-json/wp/v2/posts/${encodeURIComponent(targetId)}?context=edit`, context);
+    }
+
+    const payload = {
+      target_id: String(item.id),
+      type: item.type || 'page',
+      url: item.link || '',
+      slug: item.slug || '',
+      status: item.status || 'publish',
+      title: item.title?.raw ?? item.title?.rendered ?? '',
+      content: item.content?.raw ?? item.content?.rendered ?? '',
+      excerpt: item.excerpt?.raw ?? item.excerpt?.rendered ?? '',
+      meta: item.meta || {},
+      schema_data: item.meta?.schema_data || null,
+      yoast_title: item.meta?._yoast_wpseo_title || null,
+      yoast_metadesc: item.meta?._yoast_wpseo_metadesc || null,
+      modified_gmt: item.modified_gmt || null,
+    };
+
+    const contentHash = computeCmsPayloadHash(payload);
+    return { ...payload, content_hash: contentHash };
+  },
+
+  /**
+   * Apply reviewed, hash-locked remediation to WordPress page or post.
+   */
+  async applyRemediation(connection, remediation, context = {}) {
+    if (!remediation.reviewer) {
+      throw new Error('CMS remediation requires a named human reviewer per governance rules');
+    }
+    if (!remediation.expected_hash) {
+      throw new Error('CMS remediation requires expected_hash for hash-locking');
+    }
+    if (!remediation.target_id) {
+      throw new Error('CMS remediation requires target_id');
+    }
+
+    const current = await this.readContent(connection, remediation.target_id, context);
+    if (current.content_hash !== remediation.expected_hash) {
+      throw new Error(`stale remediation refused for WordPress ${remediation.target_id}: content hash changed (${current.content_hash} !== ${remediation.expected_hash})`);
+    }
+
+    const updates = remediation.updates || {};
+    const candidatePayload = {
+      ...current,
+      title: updates.title !== undefined ? updates.title : current.title,
+      content: updates.content !== undefined ? updates.content : current.content,
+      excerpt: updates.excerpt !== undefined ? updates.excerpt : current.excerpt,
+      slug: updates.slug !== undefined ? updates.slug : current.slug,
+      status: updates.status !== undefined ? updates.status : current.status,
+      meta: updates.meta !== undefined ? updates.meta : current.meta,
+      schema_data: updates.schema_data !== undefined ? updates.schema_data : current.schema_data,
+    };
+    const simulatedHash = computeCmsPayloadHash(candidatePayload);
+
+    // Dry-run mode by default
+    if (!context.write) {
+      return {
+        status: 'proposed',
+        dry_run: true,
+        target_id: remediation.target_id,
+        before_hash: current.content_hash,
+        after_hash: simulatedHash,
+        updates,
+        reviewer: remediation.reviewer,
+      };
+    }
+
+    // Live update
+    const base = normalizeBaseUrl(connection.property_id);
+    const endpoint = current.type === 'post' ? 'posts' : 'pages';
+    const body = {};
+    if (updates.title !== undefined) body.title = updates.title;
+    if (updates.content !== undefined) body.content = updates.content;
+    if (updates.excerpt !== undefined) body.excerpt = updates.excerpt;
+    if (updates.slug !== undefined) body.slug = updates.slug;
+    if (updates.status !== undefined) body.status = updates.status;
+    if (updates.meta !== undefined || updates.schema_data !== undefined) {
+      body.meta = {
+        ...(current.meta || {}),
+        ...(updates.meta || {}),
+        ...(updates.schema_data !== undefined ? { schema_data: updates.schema_data } : {}),
+      };
+    }
+
+    await providerRequest(`${base}/wp-json/wp/v2/${endpoint}/${encodeURIComponent(remediation.target_id)}`, {
+      ...context,
+      method: 'POST',
+      body,
+    });
+
+    const updated = await this.readContent(connection, remediation.target_id, context);
+    return {
+      status: 'applied',
+      dry_run: false,
+      target_id: remediation.target_id,
+      before_hash: current.content_hash,
+      after_hash: updated.content_hash,
+      updated_at: nowIso(),
+      reviewer: remediation.reviewer,
+    };
+  },
+};