@nebulacomponents/citable 1.18.0 → 1.18.1

package/dist/universal/.cursor/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/.cursor/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/.cursor/skills/citable/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "citable",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "managedBy": "citable-cli",
   "provider": "cursor",
   "providerName": "Cursor",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.18.0",
+  "sourcePackage": "@nebulacomponents/citable@1.18.1",
   "variantPath": ".cursor/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,12 +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:467b5f523773b4d459eeba33bf4b3445307be27058c590c0df49208956a0a2d2",
+    "schemas/sow.schema.json": "sha256:14ff2e24e03f678d3c72f97c27b0a68e117472dcc640aab7491bba1a82457906",
     "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
     "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
-    "SKILL.md": "sha256:fd34736c74771cf9375995f1e69ecd2ceda3a94042d80bb0efd6675b0a5ebc8f",
+    "SKILL.md": "sha256:d50cc48a120fee6ad3c3bf0d1bfa8ceb5bba3614bdc6af8aacc4293b9e4a1970",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:04d659518a1793d5396007fcabdc9211a8c1db8406bf4e0fa8069171fdb06518"
+    "VERSION": "sha256:71fc7bd16b1bc9b3681085fb0be8aea0b3a37d90d1685938dc2e8a31bf8c9b94"
   },
-  "treeHash": "sha256:06dcedfde2429241e5714c6e5f0ddee25dc03c53435083a1c0cc3362abdcfdb3"
+  "treeHash": "sha256:96d4589fced40f7030b6c1e48132abf2d37ebae771a1401d6f2a74e4f8fc52d1"
 }

package/dist/universal/.cursor/skills/citable/schemas/sow.schema.json

@@ -6,87 +6,404 @@
   "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" },
+    "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" }
+        },
+        "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
 }

package/dist/universal/.gemini/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.18.0
+version: 1.18.1
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -259,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