@nebulacomponents/citable 1.18.0 → 1.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.18.0",
+  "version": "1.18.2",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -52,6 +52,7 @@
     "test:integration": "node --test --test-concurrency=1 --test-reporter=spec 'tests/integration/**/*.test.js'",
     "test:e2e": "node --test --test-concurrency=1 'tests/e2e/**/*.test.js'",
     "build:dist": "node scripts/build-dist.js",
+    "validate:schemas": "node scripts/validate-schemas.js",
     "release:prepare": "node scripts/release-process.js prepare",
     "release:validate": "node scripts/release-process.js validate",
     "release:manifest": "node scripts/release-governance.js manifest",

package/schemas/cro-report.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/cro-report.schema.json",
+  "title": "Enterprise CRO & Journey Intelligence Executive Report",
+  "type": "object",
+  "required": [
+    "fact_status",
+    "report_title",
+    "client_name",
+    "target_domain",
+    "generated_at",
+    "overall_conversion_readiness",
+    "pillars",
+    "evidence_register",
+    "decision_summary",
+    "generation_provenance"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "fact_status": { "type": "string" },
+    "epistemic_status": { "type": "string" },
+    "report_title": { "type": "string" },
+    "client_name": { "type": "string" },
+    "target_domain": { "type": "string" },
+    "generated_at": { "type": "string" },
+    "overall_conversion_readiness": { "type": "number", "minimum": 0, "maximum": 100 },
+    "epistemological_framework": {
+      "type": "object",
+      "properties": {
+        "observation": { "type": "string" },
+        "hypothesis": { "type": "string" },
+        "causation": { "type": "string" },
+        "unknowns": { "type": "string" }
+      }
+    },
+    "pillars": {
+      "type": "object",
+      "required": [
+        "1", "2", "3", "4", "5", "6", "7", "8", "9", "10",
+        "11", "12", "13", "14", "15", "16", "17", "18", "19", "20",
+        "21", "22", "23", "24", "25"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[0-9]+$": {
+          "type": "object",
+          "required": ["name", "data"],
+          "properties": {
+            "name": { "type": "string" },
+            "data": {}
+          }
+        }
+      }
+    },
+    "evidence_register": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["evidence_id", "source", "methodology", "confidence_level"],
+        "properties": {
+          "evidence_id": { "type": "string", "pattern": "^EVD-CRO-[0-9]+$" },
+          "source": { "type": "string" },
+          "title": { "type": "string" },
+          "observation_date": { "type": "string" },
+          "methodology": { "type": "string" },
+          "confidence_level": { "type": "string" },
+          "data_snapshot": {}
+        }
+      }
+    },
+    "decision_summary": {
+      "type": "object",
+      "required": [
+        "observed_conversion_failures",
+        "evidence_supported_hypotheses",
+        "causal_findings",
+        "unresolved_unknowns",
+        "recommended_interventions"
+      ],
+      "properties": {
+        "observed_conversion_failures": { "type": "array", "items": { "type": "string" } },
+        "evidence_supported_hypotheses": { "type": "array", "items": { "type": "string" } },
+        "causal_findings": { "type": "array", "items": { "type": "string" } },
+        "unresolved_unknowns": { "type": "array", "items": { "type": "string" } },
+        "recommended_interventions": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "generation_provenance": {
+      "type": "object",
+      "required": [
+        "generated_at",
+        "generator_version",
+        "generation_mode",
+        "source_type",
+        "synthetic_evidence"
+      ],
+      "properties": {
+        "generated_at": { "type": "string" },
+        "generator_version": { "type": "string" },
+        "generation_mode": { "type": "string", "enum": ["CONTRACTUAL", "DRAFT", "NON_CONTRACTUAL_SAMPLE"] },
+        "source_type": { "type": "string" },
+        "source_identifier": { "type": ["string", "null"] },
+        "source_findings_count": { "type": "integer", "minimum": 0 },
+        "integrity_hash": { "type": ["string", "null"] },
+        "synthetic_evidence": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/search-report.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/search-report.schema.json",
+  "title": "Enterprise Search Intelligence & Governance Executive Report",
+  "type": "object",
+  "required": [
+    "fact_status",
+    "report_title",
+    "client_name",
+    "target_domain",
+    "generated_at",
+    "overall_readiness_score",
+    "pillars",
+    "evidence_register",
+    "decision_summary",
+    "generation_provenance"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "fact_status": { "type": "string" },
+    "epistemic_status": { "type": "string" },
+    "report_title": { "type": "string" },
+    "client_name": { "type": "string" },
+    "target_domain": { "type": "string" },
+    "generated_at": { "type": "string" },
+    "overall_readiness_score": { "type": "number", "minimum": 0, "maximum": 100 },
+    "pillars": {
+      "type": "object",
+      "required": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[0-9]+$": {
+          "type": "object",
+          "required": ["name", "data"],
+          "properties": {
+            "name": { "type": "string" },
+            "data": {}
+          }
+        }
+      }
+    },
+    "evidence_register": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["evidence_id", "source", "methodology", "confidence_level"],
+        "properties": {
+          "evidence_id": { "type": "string", "pattern": "^EVD-SRCH-[0-9]+$" },
+          "source": { "type": "string" },
+          "title": { "type": "string" },
+          "observation_date": { "type": "string" },
+          "methodology": { "type": "string" },
+          "confidence_level": { "type": "string" },
+          "data_snapshot": {}
+        }
+      }
+    },
+    "decision_summary": {
+      "type": "object",
+      "required": [
+        "confirmed_findings",
+        "inferred_opportunities",
+        "unresolved_unknowns",
+        "strategic_risks",
+        "actions_requiring_leadership_approval"
+      ],
+      "properties": {
+        "confirmed_findings": { "type": "array", "items": { "type": "string" } },
+        "inferred_opportunities": { "type": "array", "items": { "type": "string" } },
+        "unresolved_unknowns": { "type": "array", "items": { "type": "string" } },
+        "strategic_risks": { "type": "array", "items": { "type": "string" } },
+        "actions_requiring_leadership_approval": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "generation_provenance": {
+      "type": "object",
+      "required": [
+        "generated_at",
+        "generator_version",
+        "generation_mode",
+        "source_type",
+        "synthetic_evidence"
+      ],
+      "properties": {
+        "generated_at": { "type": "string" },
+        "generator_version": { "type": "string" },
+        "generation_mode": { "type": "string", "enum": ["CONTRACTUAL", "DRAFT", "NON_CONTRACTUAL_SAMPLE"] },
+        "source_type": { "type": "string" },
+        "source_identifier": { "type": ["string", "null"] },
+        "source_findings_count": { "type": "integer", "minimum": 0 },
+        "integrity_hash": { "type": ["string", "null"] },
+        "synthetic_evidence": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/sow.schema.json

@@ -6,87 +6,405 @@
   "required": [
     "sow_id",
     "version",
+    "generation_mode",
     "title",
     "client",
     "supplier",
     "effective_date",
+    "term_days",
+    "currency",
+    "currency_minor_unit_exponent",
+    "commercial_total_fee_minor",
+    "commercial_total_fee_usd",
     "executive_scope",
     "admissibility_gate",
     "work_packages",
     "deliverables",
     "acceptance_criteria",
-    "traceability_matrix"
+    "traceability_matrix",
+    "generation_provenance"
   ],
   "properties": {
-    "sow_id": { "type": "string" },
+    "$schema": { "type": "string" },
+    "sow_id": { "type": "string", "pattern": "^SOW-[A-Za-z0-9_-]+$" },
     "version": { "type": "string" },
-    "title": { "type": "string" },
+    "generation_mode": {
+      "type": "string",
+      "enum": ["CONTRACTUAL", "DRAFT", "NON_CONTRACTUAL_SAMPLE"]
+    },
+    "title": { "type": "string", "minLength": 1 },
+    "synthetic_evidence": { "type": "boolean" },
     "client": {
       "type": "object",
       "required": ["name", "contact"],
       "properties": {
-        "name": { "type": "string" },
-        "contact": { "type": "string" }
-      }
+        "name": { "type": "string", "minLength": 1 },
+        "contact": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
     },
     "supplier": {
       "type": "object",
       "required": ["name", "contact"],
       "properties": {
-        "name": { "type": "string" },
-        "contact": { "type": "string" }
-      }
+        "name": { "type": "string", "minLength": 1 },
+        "contact": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
     },
-    "effective_date": { "type": "string" },
-    "term_days": { "type": "integer" },
+    "effective_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+    "term_days": { "type": "integer", "minimum": 1 },
+    "currency": { "type": "string", "enum": ["USD"] },
+    "currency_minor_unit_exponent": { "type": "integer", "enum": [2] },
+    "commercial_total_fee_minor": { "type": "integer", "minimum": 0 },
+    "commercial_total_fee_usd": { "type": "number", "minimum": 0 },
     "executive_scope": {
       "type": "object",
       "required": ["business_objective", "in_scope_properties", "in_scope_systems"],
       "properties": {
-        "business_objective": { "type": "string" },
+        "business_objective": { "type": "string", "minLength": 1 },
         "in_scope_properties": { "type": "array", "items": { "type": "string" } },
         "in_scope_systems": { "type": "array", "items": { "type": "string" } },
         "channels": { "type": "array", "items": { "type": "string" } },
-        "geographies": { "type": "array", "items": { "type": "string" } }
-      }
+        "geographies": { "type": "array", "items": { "type": "string" } },
+        "organizational_boundaries": { "type": "string" }
+      },
+      "additionalProperties": false
     },
     "admissibility_gate": {
       "type": "object",
-      "required": ["total_findings_evaluated", "admitted_count", "refused_count"],
+      "required": ["total_findings_evaluated", "admitted_count", "refused_count", "admissibility_rate_pct", "refusal_log"],
+      "properties": {
+        "total_findings_evaluated": { "type": "integer", "minimum": 0 },
+        "admitted_count": { "type": "integer", "minimum": 0 },
+        "refused_count": { "type": "integer", "minimum": 0 },
+        "admissibility_rate_pct": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "refusal_log": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["finding_id", "subject", "gate_failed", "refusal_code", "refusal_rationale"],
+            "properties": {
+              "finding_id": { "type": "string" },
+              "detector_id": { "type": "string" },
+              "subject": { "type": "string" },
+              "gate_failed": { "type": "string" },
+              "refusal_code": { "type": "string" },
+              "refusal_rationale": { "type": "string" },
+              "suggested_handling": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "methodology": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "assumptions_and_constraints": {
+      "type": "object",
+      "required": ["assumptions", "dependencies", "exclusions", "constraints", "unresolved_unknowns"],
+      "properties": {
+        "assumptions": { "type": "array", "items": { "type": "string" } },
+        "dependencies": { "type": "array", "items": { "type": "string" } },
+        "exclusions": { "type": "array", "items": { "type": "string" } },
+        "constraints": { "type": "array", "items": { "type": "string" } },
+        "unresolved_unknowns": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "work_packages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["work_package_id", "name", "deliverable_id", "owner", "requirements"],
+        "properties": {
+          "work_package_id": { "type": "string" },
+          "name": { "type": "string" },
+          "deliverable_id": { "type": "string" },
+          "owner": { "type": "string" },
+          "requirements": { "type": "array", "minItems": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "deliverables": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["deliverable_id", "work_package_id", "title", "artifact_type", "format", "owner", "delivery_criteria"],
+        "properties": {
+          "deliverable_id": { "type": "string" },
+          "work_package_id": { "type": "string" },
+          "title": { "type": "string" },
+          "artifact_type": { "type": "string" },
+          "format": { "type": "string" },
+          "owner": { "type": "string" },
+          "delivery_criteria": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "technical_requirements": {
+      "type": "object",
+      "properties": {
+        "supported_frameworks": { "type": "array", "items": { "type": "string" } },
+        "git_branching_model": { "type": "string" },
+        "rollback_mechanism": { "type": "string" },
+        "access_requirements": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["acceptance_test_id", "sow_requirement_id", "test_description", "validation_method", "pass_threshold", "evidence_required"],
+        "properties": {
+          "acceptance_test_id": { "type": "string" },
+          "sow_requirement_id": { "type": "string" },
+          "test_description": { "type": "string" },
+          "validation_method": { "type": "string" },
+          "pass_threshold": { "type": "string" },
+          "evidence_required": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "baseline_and_target_metrics": {
+      "type": "object",
+      "properties": {
+        "disclaimer": { "type": "string" },
+        "metrics": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["metric", "baseline", "target", "validation"],
+            "properties": {
+              "metric": { "type": "string" },
+              "baseline": { "type": "string" },
+              "target": { "type": "string" },
+              "validation": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "experiment_specifications": {
+      "type": "object",
+      "properties": {
+        "standard": { "type": "string" },
+        "stopping_criteria": { "type": "string" },
+        "guardrails": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "raci_matrix": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["role", "r", "raci"],
+        "properties": {
+          "role": { "type": "string" },
+          "r": { "type": "string" },
+          "raci": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "customer_obligations": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "delivery_schedule": {
+      "type": "object",
+      "required": ["total_duration_weeks", "milestones"],
+      "properties": {
+        "total_duration_weeks": { "type": "integer", "minimum": 1 },
+        "milestones": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["milestone_id", "work_package_id", "name", "fee_minor", "fee_usd", "billing_trigger", "target_delivery_week"],
+            "properties": {
+              "milestone_id": { "type": "string" },
+              "work_package_id": { "type": "string" },
+              "name": { "type": "string" },
+              "fee_minor": { "type": "integer", "minimum": 0 },
+              "fee_usd": { "type": "number", "minimum": 0 },
+              "billing_trigger": { "type": "string" },
+              "target_delivery_week": { "type": "integer", "minimum": 1 }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "change_control_process": {
+      "type": "object",
       "properties": {
-        "total_findings_evaluated": { "type": "integer" },
-        "admitted_count": { "type": "integer" },
-        "refused_count": { "type": "integer" },
-        "refusal_log": { "type": "array" }
+        "procedure": { "type": "string" },
+        "authorization": { "type": "string" },
+        "superceding_rules": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "risk_register": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "category", "description", "mitigation"],
+        "properties": {
+          "id": { "type": "string" },
+          "category": { "type": "string" },
+          "description": { "type": "string" },
+          "mitigation": { "type": "string" }
+        },
+        "additionalProperties": false
       }
     },
-    "work_packages": { "type": "array" },
-    "deliverables": { "type": "array" },
-    "acceptance_criteria": { "type": "array" },
+    "data_governance": {
+      "type": "object",
+      "properties": {
+        "authorized_sources": { "type": "array", "items": { "type": "string" } },
+        "retention_period": { "type": "string" },
+        "processing_purpose": { "type": "string" },
+        "deletion_upon_termination": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "security_requirements": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "platform_dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "qa_plan": {
+      "type": "object",
+      "properties": {
+        "methodology": { "type": "string" },
+        "evidence_package": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "governance_model": {
+      "type": "object",
+      "properties": {
+        "weekly_sync": { "type": "string" },
+        "written_reports": { "type": "string" },
+        "decision_logging": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "commercial_terms": {
+      "type": "object",
+      "required": ["total_fixed_fee_minor", "total_fixed_fee_usd", "currency", "payment_terms", "milestones"],
+      "properties": {
+        "total_fixed_fee_minor": { "type": "integer", "minimum": 0 },
+        "total_fixed_fee_usd": { "type": "number", "minimum": 0 },
+        "currency": { "type": "string", "enum": ["USD"] },
+        "payment_terms": { "type": "string" },
+        "milestones": { "type": "array" }
+      },
+      "additionalProperties": false
+    },
+    "out_of_scope": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "warranty_terms": {
+      "type": "object",
+      "properties": {
+        "warranty_window_days": { "type": "integer", "minimum": 0 },
+        "defect_definition": { "type": "string" },
+        "exclusion": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "completion_and_handoff": {
+      "type": "object",
+      "properties": {
+        "handoff_assets": { "type": "array", "items": { "type": "string" } },
+        "operational_signoff": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "termination_provisions": {
+      "type": "object",
+      "properties": {
+        "convenience": { "type": "string" },
+        "compensation": { "type": "string" },
+        "asset_transfer": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
     "traceability_matrix": {
       "type": "array",
+      "minItems": 1,
       "items": {
         "type": "object",
         "required": [
           "finding_id",
           "recommendation",
           "sow_requirement_id",
+          "work_package_id",
           "deliverable_id",
           "acceptance_test_id",
           "owner",
-          "evidence_id"
+          "evidence_id",
+          "evidence_ids"
         ],
         "properties": {
           "finding_id": { "type": "string" },
+          "detector_id": { "type": "string" },
           "recommendation": { "type": "string" },
           "sow_requirement_id": { "type": "string" },
           "work_package_id": { "type": "string" },
           "deliverable_id": { "type": "string" },
           "acceptance_test_id": { "type": "string" },
           "owner": { "type": "string" },
-          "evidence_id": { "type": "string" }
-        }
+          "owner_source": { "type": "string" },
+          "owner_mapping_version": { "type": "string" },
+          "evidence_id": { "type": "string" },
+          "evidence_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+          "severity": { "type": "string" },
+          "target_subject": { "type": "string" },
+          "acceptance_criteria": { "type": "string" },
+          "acceptance_basis": { "type": "string" }
+        },
+        "additionalProperties": false
       }
+    },
+    "generation_provenance": {
+      "type": "object",
+      "required": [
+        "generated_at",
+        "generator_version",
+        "generation_mode",
+        "source_type",
+        "source_findings_count",
+        "synthetic_evidence"
+      ],
+      "properties": {
+        "generated_at": { "type": "string" },
+        "generator_version": { "type": "string" },
+        "generation_mode": { "type": "string", "enum": ["CONTRACTUAL", "DRAFT", "NON_CONTRACTUAL_SAMPLE"] },
+        "source_type": { "type": "string" },
+        "source_identifier": { "type": ["string", "null"] },
+        "source_findings_count": { "type": "integer", "minimum": 0 },
+        "findings_integrity_hash": { "type": ["string", "null"] },
+        "synthetic_evidence": { "type": "boolean" }
+      },
+      "additionalProperties": false
     }
-  }
+  },
+  "additionalProperties": false
 }