@nebulacomponents/citable 1.17.0 → 1.18.1

package/CHANGELOG.md

@@ -15,6 +15,68 @@ _No entries yet. See [`BOUNTY.md`](BOUNTY.md) to submit the first one._
 
 ## Unreleased
 
+## 1.18.1 — 2026-09-10
+
+### Fixed — SOW Evidence Traceability & Admissibility Gate Hardening
+
+- Hardened Scope Admissibility Gate (`src/sow/admissibilityGate.js`):
+  - Fixed acceptance gate bypass: findings without an automated rerun detector (`f.verification.detector_to_rerun`), validation method, or acceptance test are strictly refused with `REFUSE-UNVERIFIABLE`.
+  - Fixed scope boundary check: replaced naive substring matching with URL-aware hostname, subdomain, origin, and path prefix boundary validation (`checkScopeBoundary`), eliminating hostname-prefix and suffix spoofing vulnerabilities (`example.com.attacker.example`, `notexample.com`).
+  - Fixed identity conflation: separated `finding_id` from `detector_id`, ensuring deterministic uniqueness across multiple findings from the same detector.
+  - Fixed fake ownership: implemented real ownership gate resolving from `f.delivery_owner`, `f.remediation.owner`, `f.owner`, or declared engagement role mappings (`owner_source`, `owner_mapping_version`), refusing unresolved assignments with `REFUSE-OWNER-UNRESOLVED`.
+  - Fixed evidence collapsing: preserved complete supporting evidence lists in `evidence_ids[]` array without collapsing or synthesizing fallback IDs.
+  - Enforced `allowedDisciplines`: findings outside authorized disciplines are formally refused with `REFUSE-DISCIPLINE-NOT-AUTHORIZED`.
+- Hardened Statement of Work (SOW) Generator (`src/sow/generateSow.js`):
+  - Eliminated implicit hardcoded fallback findings: generation from live target or historical run fails closed when findings are missing (`NoFindingsError`). Synthetic demonstration findings are strictly confined to explicit sample mode (`--sample` / `--demo`).
+  - Added typed SOW error classes: `SowError`, `RunNotFoundError`, `FindingsMissingError`, `FindingsInvalidError`, `LiveInspectionFailedError`, `NoFindingsError`, `NoAdmissibleRequirementsError`, `BudgetCalculationError`, and `SowInvariantError`.
+  - Enforced strict run authority: explicit `--run <id>` takes absolute precedence over live scanning and fails closed if the run does not exist or findings are missing/malformed.
+  - Machine-readable `generation_provenance` block: records `generator_version`, `generated_at`, `generation_mode` (`CONTRACTUAL`, `DRAFT`, `NON_CONTRACTUAL_SAMPLE`), `source_type`, `source_identifier`, `source_findings_count`, and `findings_integrity_hash`.
+  - Canonical run chronology: established `max(canonical run timestamp)` latest-run selection with deterministic secondary key tie-breaking (`getCanonicalRunTimestamp`, `sortRunCandidatesChronologically`) across run package manifests (`manifest.json`), ISO timestamp prefixes, and findings file metadata, replacing raw directory string sorting.
+  - Unambiguous minor-unit commercial currency arithmetic: established internal integer minor units (cents, exponent 2, currency `USD`) as source of truth (`commercial_total_fee_minor`, `milestones[].fee_minor`, `commercial_terms.total_fixed_fee_minor`) via `parseCommercialBudget`, distributing remainder pennies deterministically without fractional cents or commercial leaks, rejecting negative/sub-cent budgets, and formatting major-unit USD (`fee_usd`) at presentation boundaries.
+  - Added runtime cross-object invariants validation (`validateSowInvariants`): enforces fee balancing across minor and major units, currency compliance, work package and deliverable parity, and non-empty evidence links before artifact export.
+- Hardened SOW Schema Contract (`schemas/sow.schema.json`):
+  - Enforced strict types, non-empty collections, and `additionalProperties: false` across all SOW pillars and sub-objects.
+  - Mandated `currency`, `currency_minor_unit_exponent`, `commercial_total_fee_minor`, `fee_minor`, `generation_mode`, `generation_provenance`, and `evidence_ids` in contractual requirements.
+- Hardened CLI & Exporters (`src/commands/sowCmd.js`):
+  - Added CLI options: `--sample`, `--demo`, `--draft`, `--live`, `--run`, `--scope`, `--in-scope`, `--budget-minor`, and `--min-ice`.
+  - Enforced schema validation gate in `exportSow`, rejecting any artifact that violates `schemas/sow.schema.json`.
+
+### Added — Command Contracts & Claude Agent Profiles
+
+- Added Command Contracts:
+  - `skill/commands/sow.md`: SOW generation, 7-gate scope admissibility table, standardized refusal codes, and 7-column evidence traceability matrix.
+  - `skill/commands/remediation.md`: Closed-loop code remediation, AST patch validation, confidence thresholds, and delivery kit exporter.
+  - `skill/commands/reporting.md`: Expanded with contracts for Enterprise Search Intelligence (`citable report search`) and Enterprise CRO (`citable report cro`).
+  - `skill/commands/README.md`: Matrix updated with all 13 newly implemented commands.
+- Added Managed Claude Agent Profiles:
+  - `skill/agents/citable-remediator.md`: Closed-loop code remediation specialist with AST safety validation.
+  - `skill/agents/citable-sow-architect.md`: Enterprise SOW and governance architect enforcing admissibility and traceability invariants.
+- Updated Canonical Skill & Multi-Provider Distribution:
+  - `skill/SKILL.md`: Added Enterprise SOW & governance protocol section (findings → admissibility → traceability → contract).
+  - Rebuilt distributions across 12 agent harnesses (106 packaged files per provider, 4 managed Claude agent profiles).
+
+## 1.18.0 — 2026-09-09
+
+### Added — Enterprise Search, CRO Intelligence & SOW Governance
+
+- Added Enterprise Statement of Work (SOW) generation engine (`citable sow generate`, `citable sow validate`):
+  - Contractual schema `schemas/sow.schema.json` formalizing required executive scope, admissibility gate, work packages, deliverables, acceptance criteria, and 7-column traceability matrix.
+  - 6-criterion Scope Admissibility Gate (`src/sow/admissibilityGate.js`): enforces evidence maturity, scope boundary, technical feasibility, commercial materiality (ICE-BV / severity), measurable acceptance, and ownership clarity before findings become contractual scope. Catalogues refused items in an explicit contractual refusal log with refusal codes and remediation handling.
+  - Complete 25-pillar SOW generator (`src/sow/generateSow.js`) with standalone Markdown and responsive enterprise HTML renderers.
+  - Enforced 7-column Traceability Matrix mapping: Finding ID → Recommendation → SOW Requirement ID → Deliverable ID → Acceptance Test ID → Responsible Owner → Source Evidence.
+  - Commercial terms tied strictly to verified deliverable acceptance; disclaims search rankings, AI citations, and conversion revenue guarantees in adherence to Citable governance principles.
+- Added Enterprise Split Executive Reports (`src/reporting/executiveSearchReport.js`, `src/reporting/executiveCroReport.js`, `citable report search`, `citable report cro`):
+  - Enterprise Search Intelligence Briefing: 19 pillars, evidence register traceability, fact vs inference separation, multi-engine visibility baseline, Core Web Vitals, AEO/GEO extraction posture, schema architecture, competitive SERP footprint.
+  - Enterprise CRO & Customer Journey Briefing: 25 pillars, observation vs hypothesis vs causation separation, visual saliency modeling, message-match scoring, cognitive load and abandonment friction, offer architecture, and statistical experiment design.
+- Added Technical SEO Sweep & Core Web Vitals audit (`citable sweep technical`, `src/commands/sweep.js`): static analysis of render-blocking resources, image layout shifts, and CWV readiness thresholds (LCP, INP, CLS).
+- Added On-Page Content & E-E-A-T Scoring (`citable inspect eeat`, `src/analysis/eeat.js`): 0-5 rubric scoring across Experience, Expertise, Authoritativeness, and Trustworthiness with evidence extraction.
+- Added Answer-Engine Readiness inspection (`citable inspect readiness`, `src/analysis/readiness.js`): automated multi-engine evaluation across Perplexity, Bing Copilot, and ChatGPT.
+- Added Off-Page Authority Assessment & Toxic Backlink Detection (`citable audit backlinks`, `src/commands/auditBacklinks.js`, `src/analysis/offpage.js`): identifies spam TLDs, PBN footprints, and automated disavow recommendations.
+- Added Schema.org Recommendations engine (`src/analysis/schemaRecommendations.js`, `citable schema`): evaluates content patterns to propose structured markup for FAQPage, Speakable, and HowTo.
+- Added Impact / Effort / Confidence (ICE) Prioritization Matrix (`citable prioritize matrix`, `src/analysis/iceMatrix.js`): scoring matrix categorizing findings into Quick Wins, Strategic Bets, Low-Hanging Fruit, and Deprioritized.
+- Added 30/90/180-Day Strategic & CRO Milestone Roadmaps (`citable roadmap strategic`, `citable cro roadmap`, `src/analysis/strategicRoadmap.js`, `src/analysis/croRoadmap.js`): phased implementation schedules tied to verified technical deliverables and conversion metrics.
+- Added End-to-End CRO Intelligence Suite (`citable cro`, `src/commands/croSuite.js`, `src/analysis/croAudit.js`, `src/analysis/funnelAnalysis.js`, `src/analysis/behavioral.js`): conversion path continuity, above-the-fold clarity, trust and objection analysis, and prioritized A/B experiment backlog with statistical power blueprints.
+
 ## 1.17.0 — 2026-09-08
 
 ### Added — Closed-Loop Remediation & Customer Fulfillment (Nebula Release Requests)

package/dist/universal/.agents/skills/citable/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.17.0
+version: 1.18.1
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -88,7 +88,13 @@ prefer running it over re-deriving its checks by hand:
 citable init                        # initialize .citable/ (non-destructive)
 citable audit [scope] --target <dir|url> [--base-url <url>] [--ref-date YYYY-MM-DD]
 citable plan-audit --target <dir|url> [--base-url <url>]
+citable sweep technical --target <dir|url> # Technical SEO sweep + Core Web Vitals metrics
 citable inspect <page> --target <dir|url>
+citable inspect eeat <page> --target <dir|url> # On-page content analysis & 0-5 E-E-A-T score
+citable inspect readiness <page> --target <dir|url> # Answer-engine readiness (Perplexity, Copilot, ChatGPT)
+citable audit backlinks --input <file>  # Off-page authority assessment & toxic domain identification
+citable prioritize matrix [--run <run-id>] # Impact/Effort/Confidence (ICE) scoring matrix
+citable roadmap [generate|show]         # 30/90/180-day strategic milestone roadmap
 citable map-claims --target <dir|url> [--write]
 citable substantiate [--write]
 citable schema --target <dir|url>
@@ -109,6 +115,8 @@ citable monitor [runA runB] [--webhook <url>] [--min-severity <sev>]  # observat
 citable report dashboard [--last N] [--since <run-id>]  # cross-run evidence trend (Markdown + HTML)
 citable report share-of-voice [--last N] [--since <run-id>]  # competitor citation share (Markdown + HTML)
 citable report consensus [--last N] [--since <run-id>]  # canonical discovery consensus matrix (Markdown + HTML)
+citable report search [--target <dir|url>] [--run <id>] [--format md|html|json] # Enterprise Search Intelligence Briefing (19 pillars, evidence-traceable)
+citable report cro [--target <dir|url>] [--input <file>] [--format md|html|json] # Enterprise CRO & Journey Briefing (25 pillars: observations vs hypotheses vs causation)
 citable metrics import --provider <name> --input <csv|json>
 citable connect status
 citable connect configure --provider <gsc|ga4|wordpress|webflow> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
@@ -143,6 +151,15 @@ citable artifacts export <run-id> --output <directory>
 citable artifacts verify --input <directory>
 citable artifacts import --input <directory>
 citable inspect cro <page> --target <dir|url>   # CRO readiness: CTAs, forms, payment-wallet vs authentication readiness, modeled saliency indices
+citable cro [--target <dir|url>] [--funnel <id>] # Full CRO intelligence suite: funnel, ATF clarity, trust, cognitive load, ICE matrix, roadmap
+citable cro backlog [--target <dir|url>]         # Prioritized A/B experiment backlog with falsifiable hypotheses & guardrails
+citable cro roadmap [--target <dir|url>]         # 30/90/180-day CRO strategic roadmap tied to measurable conversion outcomes
+citable sweep technical [--target <dir|url>]    # Technical SEO sweep with Core Web Vitals readiness metrics (LCP, INP, CLS)
+citable inspect eeat <page> --target <dir|url>  # On-page E-E-A-T evaluation on a 0-5 rubric scale
+citable inspect readiness <page> --target <dir|url> # Answer-engine readiness across Perplexity, Bing Copilot, ChatGPT
+citable audit backlinks --input <backlinks.json> # Off-page authority assessment and toxic domain identification
+citable prioritize matrix                       # Impact/Effort/Confidence (ICE) scoring matrix for findings & roadmap
+citable roadmap strategic                       # 30/90/180-day strategic milestone horizons with KPI linkages
 citable preview cro <page> [--export <file.html>]  # split-screen before/remediated sandbox (layout-contract checked; accessibility-aware)
 citable remediate --finding <id> [--target <file>] [--write]  # production-safe patch: framework detection, unified diff, static validation, confidence gate, rollback snapshot; semantic copy changes always refuse automated write
 citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]  # closed loop: re-run the detector and emit a before/after evidence bundle (schema remediation-verification)
@@ -150,6 +167,8 @@ citable verify page <page> --target <dir|url>   # all detectors scoped to one pa
 citable check experiment <id> [--observed-control N --observed-variant N --days-running N]  # SRM, stopping, power, contamination; lifecycle: planned|running|inconclusive|validated
 citable compatibility   # Node engine, optional adapters, browser, framework, registries, edge size limits
 citable kit export --run <run-id> --finding <id> [--target <file>]  # customer-ready implementation kit (finding, diff, evidence, acceptance tests, deployment, limitations)
+citable sow generate [--target <dir|url>] [--budget <amount>] [--format md|html|json] [--output <path>] # Enterprise SOW from findings with 6-gate admissibility & 7-column traceability
+citable sow validate <sow.json>                  # Validate SOW schema, admissibility gates, and complete traceability matrix
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -240,6 +259,27 @@ The CRO suite completes the loop. Rules that govern every step:
    payload in the `citable_output_schema` 1.0 envelope
    (`schemas/cli-output-envelope.schema.json`).
 
+## Enterprise SOW & governance protocol (findings → admissibility → traceability → contract)
+
+The SOW engine (`citable sow generate`, `citable sow validate`) translates verified audit findings into legally enforceable enterprise Statements of Work:
+
+1. **Authoritative Evidence Gating**: A contractual SOW requires verified audit findings from `--run <id>` or a live target. Never invent or synthesize findings in `CONTRACTUAL` or `DRAFT` modes; missing findings fail closed (`NoFindingsError`). Synthetic baseline findings are strictly confined to `--sample` / `--demo`.
+2. **Scope Admissibility Filter**: Audit findings do not automatically become contractual obligations. Every candidate finding must pass 7 objective gates:
+   - *Exclusion Gate*: No explicitly blacklisted detectors (`REFUSE-EXCLUDED`).
+   - *Discipline Authorization*: Finding discipline must be authorized in engagement terms (`REFUSE-DISCIPLINE-NOT-AUTHORIZED`).
+   - *Evidence Maturity*: Deterministic/observed confidence with real evidence (`REFUSE-EXPERIMENTAL`, `REFUSE-NO-EVIDENCE`).
+   - *Scope Boundary*: URL matches contracted origins, hosts, or paths (`REFUSE-OUT-OF-SCOPE`).
+   - *Technical Feasibility*: Reject legal, trademark, GDPR, or unfeasible remediation (`REFUSE-UNFEASIBLE-REMEDIATION`).
+   - *Commercial Materiality*: High severity or ICE score >= min threshold (`REFUSE-LOW-MATERIALITY`).
+   - *Measurable Acceptance*: Automated verification rerun detector or test (`REFUSE-UNVERIFIABLE`).
+   - *Ownership Clarity*: Resolvable accountable delivery owner (`REFUSE-OWNER-UNRESOLVED`).
+   All refused findings are logged in `admissibility_gate.refusal_log`. Never force a refused item into scope.
+3. **The 7-Column Traceability Matrix**: Every admitted requirement must strictly link:
+   `Finding ID → Recommendation → SOW Req ID → Deliverable ID → Acceptance Test ID → Responsible Owner → Source Evidence IDs`.
+4. **Commercial Integer Minor-Unit Arithmetic**: Milestone fee calculations are performed strictly in integer minor units (cents, exponent 2, currency `USD`) via `parseCommercialBudget` and `allocateMilestoneFees`. Remainder pennies are distributed deterministically across initial milestones. Fractional sub-cents (`100.001`) and negative budgets are rejected. Milestone fees and total fees must balance to the exact integer cent.
+5. **No Outcome Guarantees**: Fees are tied exclusively to verified deliverable acceptance and closed-loop test execution. Ranking, citation presence, and conversion revenue guarantees are strictly disclaimed.
+6. **Schema Validation Gate**: Exported SOW artifacts must validate against `schemas/sow.schema.json` with `additionalProperties: false`.
+
 ## Command workflows
 
 Detailed per-command workflows live in `commands/`. Follow them; they define

package/dist/universal/.agents/skills/citable/VERSION

@@ -1 +1 @@
-1.17.0
+1.18.1

package/dist/universal/.agents/skills/citable/agents/citable-remediator.md

@@ -0,0 +1,43 @@
+---
+name: citable-remediator
+description: Execute closed-loop code remediation, AST patch validation, detector rerun verification, and customer delivery kit generation. Not for unreviewed direct file writes, semantic copy generation, or outcome promises.
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+model: inherit
+maxTurns: 25
+skills:
+  - citable
+---
+
+You are Citable's closed-loop remediation specialist. Your responsibility is to take verified audit findings, apply safe, idempotent AST patches, verify that target detectors are resolved with zero regressions, and generate customer implementation packages.
+
+## Authority boundary
+
+- You may run `citable remediate`, `citable verify remediation`, `citable kit export`, and `citable lint components`.
+- Never edit target source files using ad-hoc text manipulation or unvalidated shell scripts. All code mutations must flow through `citable remediate` with AST validation.
+- Refuse automated writes on semantic copy or editorial content (CRO-012, COMP-003); microcopy decisions belong to human editors (fact ≠ inference).
+- Always verify that a rollback snapshot exists under `.citable/remediation/snapshots/` before writing to disk.
+- Never claim a finding is fixed until `citable verify remediation` confirms the source detector no longer flags the target surface.
+- Never promise ranking gains, AI citation rates, or conversion lift.
+
+## Workflow
+
+1. **Finding Triage**: Identify the finding ID, source run, and target file. Inspect the finding's observation and remediation recommendation.
+2. **Dry-Run Inspection**: Execute `citable remediate --finding <id> [--target <file>]` (dry-run by default) to inspect the unified diff, framework classification, and confidence score.
+3. **Confidence Gate**: If `computeConfidence` is below `0.70`, or if the patch involves editorial copy, report `patch_refused` with required human inputs.
+4. **Gated Write**: If confidence is sufficient and structural validation passes, run `citable remediate --finding <id> --write`.
+5. **Closed-Loop Verification**: Run `citable verify remediation --run <run-id> --finding <id> [--target <file>]` to re-execute the source detector against the patched file and check for regressions.
+6. **Delivery Kit Export**: If verified, run `citable kit export --run <run-id> --finding <id>` to generate an engineer-ready delivery kit with tests, diffs, and rollback instructions.
+
+## Return contract
+
+Report:
+1. Target finding ID, file path, and detected framework;
+2. Unified diff and structural AST validation verdict;
+3. Rollback snapshot path and integrity hash;
+4. Closed-loop verification verdict (`verified`, `not_resolved`, `blocked`, or `patch_refused`);
+5. Regression sweep results (verifying zero new critical/high defects);
+6. Delivery kit path and customer acceptance criteria.

package/dist/universal/.agents/skills/citable/agents/citable-sow-architect.md

@@ -0,0 +1,43 @@
+---
+name: citable-sow-architect
+description: Generate contractually enforceable Statements of Work, evaluate Scope Admissibility Gates, enforce 7-column evidence traceability, and compile enterprise search/CRO intelligence briefings. Not for fabricated findings, unevidenced scope, or commercial guarantees.
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+model: inherit
+maxTurns: 25
+skills:
+  - citable
+---
+
+You are Citable's enterprise engagement and SOW architect. Your responsibility is to transform empirical audit findings into contractually enforceable, evidence-traceable Statements of Work (SOWs) and split executive intelligence briefings.
+
+## Authority boundary
+
+- You may run `citable sow generate`, `citable sow validate`, `citable report search`, `citable report cro`, and read audit runs.
+- Never synthesize or hallucinate findings in `CONTRACTUAL` mode. If audit evidence is missing, fail closed and report `NO_FINDINGS`. Synthetic findings are strictly confined to `--sample` / `--demo`.
+- Never force an unqualified finding through the Admissibility Gate. Refused findings must be preserved in `admissibility_gate.refusal_log` with standard refusal codes.
+- Enforce integer minor-unit arithmetic (cents, exponent 2, currency `USD`) for all fees. Never allow fractional pennies or budget drift across milestones.
+- Strictly uphold Citable governance principles: **no search engine crawling, indexation, ranking, AI answer citation, or conversion revenue is guaranteed**. Fees are bound exclusively to verified deliverable acceptance.
+
+## Workflow
+
+1. **Source Evidence Resolution**: Determine the authoritative evidence source: explicit run (`--run <id>`), live scan (`--target <url>`), or sample demonstration (`--sample`). Explicit `--run` takes precedence.
+2. **Admissibility Gating**: Evaluate findings through the 7 admissibility gates (maturity, boundary, feasibility, materiality, acceptance, ownership, discipline). Record refused items in the contractual refusal log.
+3. **Traceability Binding**: Construct the 7-column matrix ensuring every requirement links: Finding ID → Recommendation → SOW Requirement ID → Deliverable ID → Acceptance Test ID → Owner → Source Evidence.
+4. **Commercial Minor-Unit Calculation**: Allocate milestone fees using integer minor units (`commercial_total_fee_minor`) with deterministic penny remainder distribution.
+5. **Contractual Export**: Generate SOW artifacts in Markdown, HTML, or JSON (`citable sow generate`).
+6. **Integrity Validation**: Run `citable sow validate <sow.json>` to verify strict schema conformance against `schemas/sow.schema.json` and cross-object runtime invariants.
+7. **Companion Briefings**: If executive reporting is requested, generate the companion 19-pillar Search Intelligence Briefing (`citable report search`) or 25-pillar CRO Briefing (`citable report cro`).
+
+## Return contract
+
+Report:
+1. SOW ID, generation mode (`CONTRACTUAL`, `DRAFT`, `NON_CONTRACTUAL_SAMPLE`), and generator provenance;
+2. Commercial total value, currency (`USD`), minor units, and milestone fee schedule;
+3. Admissibility gate statistics: total findings, admitted count, refused count, and refusal codes;
+4. 7-column Traceability Matrix summary;
+5. Schema validation verdict against `schemas/sow.schema.json`;
+6. Output artifact paths (Markdown, HTML, JSON).

package/dist/universal/.agents/skills/citable/commands/README.md

@@ -42,6 +42,19 @@ intent, not executability, so statuses are strict:
 | /citable validate-render | partially implemented by `observe render`; fixed Chromium profiles and schema-validated Chromium/Firefox/WebKit journeys are implemented, while reviewed semantic-impact detectors and reusable application-specific journey libraries remain |
 | /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
 | `citable artifacts export/verify/import` | implemented — portable, versioned, checksum-bound run interchange without hosted-service authority |
+| /citable sow generate / validate | implemented — 25-pillar SOW with 7-gate admissibility, 7-column traceability matrix, and integer minor-unit arithmetic (sow.md) |
+| /citable report search / cro | implemented — split 19-pillar Search and 25-pillar CRO executive briefings with observation vs hypothesis vs causation taxonomy (reporting.md) |
+| /citable sweep technical | implemented — static Core Web Vitals readiness analysis (LCP, INP, CLS) |
+| /citable inspect eeat / inspect readiness | implemented — on-page 0-5 E-E-A-T rubric scoring and multi-answer-engine readiness (Perplexity, Copilot, ChatGPT) |
+| /citable audit backlinks | implemented — off-page authority assessment, toxic TLD detection, and disavow generator |
+| /citable prioritize matrix | implemented — Impact / Effort / Confidence (ICE) scoring matrix for findings |
+| /citable roadmap strategic / cro roadmap | implemented — 30/90/180-day milestone implementation roadmaps |
+| /citable cro / cro backlog | implemented — conversion path continuity, message match, cognitive friction, and falsifiable experiment backlog |
+| /citable remediate / verify remediation / kit export | implemented — framework detection, idempotent AST patches, confidence gate, detector rerun verification, and customer delivery kits (remediation.md) |
+| /citable check experiment | implemented — sample-ratio mismatch (SRM), early stopping, and statistical power guardrails |
+| /citable test visual / preview cro | implemented — visual layout contract testing and accessibility-aware preview sandbox |
+| /citable compatibility | implemented — pre-flight runtime, dependency, framework, and edge worker diagnostics |
+| /citable corpus benchmark | implemented — golden benchmark corpus evaluation with per-detector precision/recall gates |
 
 Shared refusal conditions (all commands): any action that would fabricate
 facts, citations, evidence, authorship, reviews, corroboration, or hidden

package/dist/universal/.agents/skills/citable/commands/remediation.md

@@ -0,0 +1,55 @@
+---
+command: /citable remediate --finding <id> [--target <file>] [--write]
+purpose: Apply safe, validated AST code patches for deterministic defects with automated rollback snapshots, structural syntax validation, and confidence gating.
+preconditions: [valid finding from audit run; target source file identified and writeable]
+failure_behaviour: unknown framework -> fail closed; invalid syntax after patch -> rollback and refuse; confidence < 0.7 -> refuse write; semantic microcopy changes -> always refuse automated write (human editorial decision required)
+artifacts_created: [.citable/remediation/snapshots/<snapshot-id>/, unified diff on stdout]
+---
+
+# Closed-Loop Code Remediation & Verification
+
+The remediation suite provides safe, gated code fixes for deterministic technical, schema, and CRO defects discovered during audits. It bridges the gap between audit findings and customer-verified pull requests.
+
+## 1. Safe Patch Application (`citable remediate`)
+
+1. **Framework Detection**: Identifies target source syntax (`jsx`, `tsx`, `vue`, `html`). Fails closed on unknown or ambiguous frameworks.
+2. **Idempotent AST Patching**: Patches are mathematically verified to be idempotent (`applyPatchDetailed`): applying the patch a second time produces an identical AST (a fixed point).
+3. **Structural Validation Gate**: Runs `validatePatchedSource` to confirm that the patch does not break AST structure, introduce syntax errors, or alter unrelated code blocks.
+4. **Confidence Threshold**: Computes an explicit multi-factor confidence score (`computeConfidence`). `--write` is refused if confidence falls below `0.70`.
+5. **Editorial Boundary (Semantic Microcopy Refusal)**: Automated `--write` is strictly refused for semantic copy, CTA wording, or headline changes (e.g. `CRO-012`, `COMP-003`). Microcopy is a human editorial and brand judgment (fact ≠ inference).
+6. **Rollback Snapshot**: Every `--write` automatically snapshots the target file under `.citable/remediation/snapshots/<timestamp>/` with a SHA-256 manifest before making any disk modifications.
+
+## 2. Closed-Loop Verification (`citable verify remediation`)
+
+Running a patch is NOT proof that a defect is resolved:
+
+```bash
+citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]
+```
+
+1. **Deterministic Detector Rerun**: Re-executes the exact source detector (`detector_to_rerun`) against the patched target.
+2. **Regression Sweep**: Sweeps for newly introduced critical or high severity defects compared to the baseline run.
+3. **Verification Envelopes**: Emits a checksum-bound before/after verification envelope conforming to `schemas/remediation-verification.schema.json`.
+4. **Verdict Classification**:
+   * `verified`: Target detector no longer reports the defect; zero regressions introduced.
+   * `not_resolved`: Target detector still detects the condition on the patched surface.
+   * `blocked`: Prerequisite dependencies, build tools, or environments unavailable.
+   * `patch_refused`: Confidence below threshold, semantic copy gated, or syntax check failed.
+5. **Outcome Boundary**: Resolution means the detector no longer flags the subject — **it is never an outcome guarantee of rankings, AI citations, or conversion lift**.
+
+## 3. Customer Implementation Kits (`citable kit export`)
+
+Produce an engineer-ready delivery kit for customer development teams:
+
+```bash
+citable kit export --run <run-id> --finding <id> [--target <file>]
+```
+
+Creates a self-contained directory containing:
+* Verbatim finding with evidence lineage.
+* Exact unified diff for code review.
+* Reusable Nebula design system component template (React / Vue / HTML).
+* Rendering-evidence manifest (real captured DOM/visual state; synthetic evidence forbidden).
+* Acceptance test criteria and re-audit verification script.
+* Deployment and rollback instructions.
+* Explicit technical limitations and non-guarantee disclosures.

package/dist/universal/.agents/skills/citable/commands/reporting.md

@@ -71,3 +71,31 @@ any observed change to a specific intervention.
    authoritative index guarantees. Divergences are reported as factual observations,
    never fabricated or interpolated.
 
+# Enterprise Search Intelligence Briefing (`citable report search`)
+
+1. Run `citable report search [--target <dir|url>] [--run <id>] [--format md|html|json] [--output <file>]`
+   to generate the 19-pillar Executive Search Intelligence Briefing.
+2. Synthesizes technical crawlability, indexation, Core Web Vitals readiness,
+   AEO answer-extractability, GEO citation frequency, knowledge graph schema
+   architecture, and competitor SERP landscape into an executive document.
+3. Every recommendation binds to a verified finding in the Evidence Register.
+4. Facts and inferences are strictly segregated: deterministic observations are
+   reported in green data panels; strategic hypotheses and inferences are explicitly
+   labeled with confidence ratings.
+5. Refusal boundary: Never promises rankings, algorithmic immunity, or indexing
+   guarantees.
+
+# Enterprise CRO & Customer Journey Briefing (`citable report cro`)
+
+1. Run `citable report cro [--target <dir|url>] [--input <file>] [--format md|html|json] [--output <file>]`
+   to generate the 25-pillar Executive Conversion & Customer Journey Briefing.
+2. Covers end-to-end conversion paths: above-the-fold clarity, message-match
+   scoring, cognitive load, checkout friction, trust and objection analysis, offer
+   architecture, and prioritized A/B experiment blueprints.
+3. Strictly adheres to the **Observation vs Hypothesis vs Causation** taxonomy:
+   - **Observations**: Verbatim DOM defects (e.g. missing autocomplete, undersized touch targets).
+   - **Hypotheses**: Falsifiable experiment statements with measurable primary metrics and guardrails.
+   - **Causation**: Statistical lift attribution requiring concluded, SRM-clean A/B experiments.
+4. Refusal boundary: Revenue lift, conversion percentage improvements, and visual
+   saliency scores are modeled heuristic indices, never observed behavior or guaranteed revenue.
+

package/dist/universal/.agents/skills/citable/commands/sow.md

@@ -0,0 +1,95 @@
+---
+command: /citable sow generate [--target <dir|url>] [--run <id>] [--budget <amount>] [--budget-minor <cents>] [--format md|html|json] [--output <path>] [--sample] [--draft]
+purpose: Generate a contractually binding, evidence-traceable enterprise Statement of Work (SOW) from verified audit findings through a formal 7-gate scope admissibility filter and 7-column traceability matrix.
+preconditions: [at least one finalized audit run with verified findings or live target; sample mode required for synthetic demonstrations]
+failure_behaviour: absent or unverified findings in contractual mode -> NoFindingsError; all findings refused -> NoAdmissibleRequirementsError; non-existent run -> RunNotFoundError; negative or sub-cent budget -> BudgetCalculationError; invariant drift -> SowInvariantError
+artifacts_created: [SOW.md, SOW.html, or SOW.json at specified output path]
+---
+
+# Enterprise Statement of Work (SOW) Contract
+
+The `citable sow` command generates enterprise-grade, evidence-backed Statements of Work derived from verified technical SEO, AEO, GEO, schema, and CRO audit findings. It establishes rigid, downward traceability:
+
+```text
+Evidence (observation envelope)
+  ↓
+Observation (deterministic DOM / HTTP probe)
+  ↓
+Finding (verified defect / friction)
+  ↓
+Recommendation (governed remediation)
+  ↓
+SOW Requirement (contractual scope)
+  ↓
+Deliverable (code patch / AST modification)
+  ↓
+Acceptance Test (automated closed-loop detector rerun)
+```
+
+## 1. Operating Premises & Commercial Disclaimers
+
+1. **Fee Binding**: Supplier fees are bound exclusively to verified deliverable acceptance and closed-loop test execution.
+2. **Strict Outcome Disclaimers**: In strict compliance with Citable governance principles, **no search engine crawling, indexation, ranking, AI answer citation, or conversion revenue is guaranteed**.
+3. **No Synthetic Data in Contracts**: Attempting to generate a `CONTRACTUAL` SOW without verified empirical findings immediately fails closed with `NoFindingsError`. Synthetic findings are strictly confined to `--sample` / `--demo`.
+
+## 2. The Scope Admissibility Gate
+
+Audit findings do NOT automatically become contractual obligations. Every candidate finding must pass 7 admissibility gates:
+
+| Gate | Verification Check | Failure Refusal Code | Contractual Handling |
+| :--- | :--- | :--- | :--- |
+| **1. Exclusion Gate** | Check against explicit excluded detectors list | `REFUSE-EXCLUDED` | Track in internal backlog; execute under separate advisory engagement. |
+| **2. Discipline Authorization** | Check if discipline is authorized under contract | `REFUSE-DISCIPLINE-NOT-AUTHORIZED` | Expand authorized disciplines in SOW engagement terms or contract under separate SOW. |
+| **3. Evidence Maturity** | Require deterministic/observed confidence & evidence | `REFUSE-EXPERIMENTAL` / `REFUSE-NO-EVIDENCE` | Run controlled observation probes before considering for contractual obligation. |
+| **4. Scope Boundary** | Verify URL matches authorized host, subdomain, or path | `REFUSE-OUT-OF-SCOPE` | Escalate domain ownership verification or expand contractual executive scope. |
+| **5. Feasibility Gate** | Reject legal, trademark, GDPR, or unfeasible remediation | `REFUSE-UNFEASIBLE-REMEDIATION` | Refer to specialized legal or compliance counsel outside scope. |
+| **6. Materiality Gate** | Require critical/high severity or ICE score >= threshold | `REFUSE-LOW-MATERIALITY` | Log to internal product maintenance backlog; omit from high-value SOW. |
+| **7. Acceptance Gate** | Require automated rerun detector or objective pass/fail test | `REFUSE-UNVERIFIABLE` | Define deterministic verification criteria before adding to scope. |
+| **8. Ownership Clarity** | Resolve accountable owner from finding or role mappings | `REFUSE-OWNER-UNRESOLVED` | Specify delivery_owner on finding or map discipline to accountable role. |
+
+All refused findings are recorded in the SOW's `admissibility_gate.refusal_log` with standard refusal codes and contractual handling guidance.
+
+## 3. The 7-Column Traceability Matrix
+
+Every admitted requirement must satisfy complete 7-column bidirectional traceability:
+
+1. **Finding ID**: Verbatim identifier of the empirical defect (e.g. `F-TECH-001`).
+2. **Recommendation**: Governed, safe remediation instruction.
+3. **SOW Requirement ID**: Contractual clause identifier (`REQ-SOW-001`).
+4. **Deliverable ID**: Accountable work package deliverable (`DELIV-01`).
+5. **Acceptance Test ID**: Automated closed-loop test (`ACC-TEST-001`).
+6. **Responsible Owner**: Named lead dev, architect, or agency practice owner.
+7. **Source Evidence IDs**: Array of cryptographic observation IDs (`['EVD-CWV-001']`).
+
+## 4. Commercial Currency & Minor-Unit Semantics
+
+To eliminate commercial fee drift and rounding leaks, all internal calculations use exact **integer minor units (cents, exponent 2, currency `USD`)**:
+
+* `currency`: Declared as `USD`.
+* `currency_minor_unit_exponent`: Declared as `2`.
+* `commercial_total_fee_minor`: Integer cents (e.g. `$50,000.00` = `5000000` cents).
+* `milestones[].fee_minor`: Integer floor allocation across milestones with remainder pennies distributed deterministically to initial milestones.
+* `commercial_total_fee_usd` / `milestones[].fee_usd`: Derived dollar representation formatted at presentation boundaries (`$33.34`, `$50,000`).
+* Sub-cent fractional budgets (`100.001`) and negative budgets are strictly rejected.
+
+## 5. Generation Modes & Machine-Readable Provenance
+
+Every generated SOW embeds an immutable `generation_provenance` block:
+
+* **`CONTRACTUAL`**: Generated from verified historical run findings or live target; synthetic evidence forbidden.
+* **`DRAFT`**: Generated with preliminary scope or unfinalized commercial terms; requires executive sign-off.
+* **`NON_CONTRACTUAL_SAMPLE`**: Generated with synthetic baseline findings strictly for evaluation/demo (`--sample`).
+
+Provenance tracks:
+* `generator_version`: Exact Citable semver.
+* `generated_at`: ISO 8601 timestamp.
+* `source_type`: `HISTORICAL_RUN`, `LIVE_INSPECTION`, `DIRECT_FINDINGS`, or `SAMPLE_BASELINE`.
+* `source_identifier`: Target URL, run ID, or sample identifier.
+* `source_findings_count`: Integer count of evaluated findings.
+* `findings_integrity_hash`: SHA-256 hash of input findings.
+
+## 6. SOW Verification Command
+
+Run `citable sow validate <sow.json>` to verify:
+1. Strict schema compliance against `schemas/sow.schema.json` (`additionalProperties: false`).
+2. Cross-object invariants via `validateSowInvariants` (fee balancing, work package and deliverable parity, non-empty evidence links).

package/dist/universal/.agents/skills/citable/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "citable",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "managedBy": "citable-cli",
   "provider": "codex",
   "providerName": "OpenAI Codex",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.17.0",
+  "sourcePackage": "@nebulacomponents/citable@1.18.1",
   "variantPath": ".agents/skills/citable",
   "agentProfiles": {
     "status": "unsupported",
@@ -13,7 +13,9 @@
   },
   "files": {
     "agents/citable-auditor.md": "sha256:06fe8d84834b2c09b7e7083aa6f57e94e837e0643dbe4ead4bbecf651fb41cad",
+    "agents/citable-remediator.md": "sha256:c990e929f411fc2f2de3aca759333502c956e96924b3a0f809ab0927062623dc",
     "agents/citable-semantic-reviewer.md": "sha256:77582263a048ea41ae3f7ee326dbd036222fab81ed83bda98034ec83ee21ef2e",
+    "agents/citable-sow-architect.md": "sha256:d55cf8bc2ab8f364c0d95ec39fc44406684110d1e4d1ff2e34702ded003094b4",
     "commands/action-findings.md": "sha256:b1d5c4d8d8b1092bc73b99430bea0a2e460031658e42bed33eb94da9a3c0e48f",
     "commands/artifact-interchange.md": "sha256:18d56fbfa6bb3f23f08593a9a8135e51c268618b049e53c793969b68000875c3",
     "commands/delivery.md": "sha256:3b29250f9e9f84442812e320a70d5d2784b4286e91af3866f99cb6062a85a10f",
@@ -26,9 +28,11 @@
     "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
     "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
     "commands/plan-audit.md": "sha256:69875c9654e13b84566dafb16afe5afe08cffb9f3bded1f2d8d2261ae871c869",
-    "commands/README.md": "sha256:9c25573c8af30a8cf02f450f5f3812769aca01ebb422d600e830e78955f18c4a",
-    "commands/reporting.md": "sha256:ae89f8620acfef645d52bfe715efa332fdb8f464d890e45240ea341b24adb985",
+    "commands/README.md": "sha256:683b226020582dd93e24a2fb59ce6264735f44eb26353f977153034a615f871c",
+    "commands/remediation.md": "sha256:7f983ecf63ec6741fa7e291243c6faeb44a5b140655a5ec3a62bcbc4c16d8870",
+    "commands/reporting.md": "sha256:f560f3c8349fcdaf6d3c3a27968016e20ef42ef2473292f7b83260cfb4b3b2e6",
     "commands/reviews.md": "sha256:902904aaa405fe5724cf0662c7a5a36eab9a4fe0eb81cbd95ffa2fff946e0ac8",
+    "commands/sow.md": "sha256:576c0ff119e5a9193476c20aee65019dbe91502d624d3a8fc8469915a3bc2b19",
     "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
     "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
     "references/aeo-geo-validation.md": "sha256:4b0041764f2fdbfbff1e1a2907eaed02cf0aef491254a9c98ec9250ff1084e80",
@@ -108,11 +112,12 @@
     "schemas/scenario.schema.json": "sha256:3f5bc2032d08f973600db068f475176a0e4706b33be42f99c778fe755a0ff38b",
     "schemas/schedule.schema.json": "sha256:645df065bf33577a960c0bf8bb97e141e9326840303569468dae8a553d468482",
     "schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
+    "schemas/sow.schema.json": "sha256:14ff2e24e03f678d3c72f97c27b0a68e117472dcc640aab7491bba1a82457906",
     "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
     "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
-    "SKILL.md": "sha256:f39e0863bbcaf178c46afed4ae95834451d96e6b1d07af3883733de707e692ea",
+    "SKILL.md": "sha256:d50cc48a120fee6ad3c3bf0d1bfa8ceb5bba3614bdc6af8aacc4293b9e4a1970",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:00afc49f1599e59129a59b64c2b019de3fe35300c05bb9d96cb25002576ff43b"
+    "VERSION": "sha256:71fc7bd16b1bc9b3681085fb0be8aea0b3a37d90d1685938dc2e8a31bf8c9b94"
   },
-  "treeHash": "sha256:e4c2165da7ae3106c3bfa358445d2e51dd974f656d058bc03f22fd0604d2d4b3"
+  "treeHash": "sha256:96d4589fced40f7030b6c1e48132abf2d37ebae771a1401d6f2a74e4f8fc52d1"
 }