@nebulacomponents/citable 1.18.0 → 1.18.2

package/src/sow/generateSow.js

@@ -4,143 +4,468 @@ import { buildContext } from '../commands/context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, indexTargets } from '../detectors/framework.js';
 import { evaluateScopeAdmissibility } from './admissibilityGate.js';
-import { readJson, nowIso } from '../shared/io.js';
+import { readJson, nowIso, sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import {
+  resolveEvidenceSource,
+  getCanonicalRunTimestamp,
+  sortRunCandidatesChronologically,
+} from '../shared/evidenceSourceResolver.js';
+import {
+  escapeHtml,
+  escapeHtmlAttr,
+  sanitizeUrl,
+  escapeMarkdownTableCell,
+  sanitizeForMarkdown,
+} from '../shared/htmlEscape.js';
+
+/**
+ * Typed SOW Domain Errors
+ */
+export class SowError extends Error {
+  constructor(message, code = 'SOW_ERROR') {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+  }
+}
+
+export class RunNotFoundError extends SowError {
+  constructor(runId) {
+    super(`Specified run not found: ${runId}`, 'RUN_NOT_FOUND');
+    this.runId = runId;
+  }
+}
+
+export class FindingsMissingError extends SowError {
+  constructor(runId, filePath) {
+    super(`Run ${runId} is missing findings.json at ${filePath}`, 'FINDINGS_MISSING');
+    this.runId = runId;
+    this.filePath = filePath;
+  }
+}
+
+export class FindingsInvalidError extends SowError {
+  constructor(runId, message) {
+    super(`Run ${runId} contains malformed or invalid findings: ${message}`, 'FINDINGS_INVALID');
+    this.runId = runId;
+  }
+}
+
+export class LiveInspectionFailedError extends SowError {
+  constructor(target, reason) {
+    super(`Live target inspection failed for ${target}: ${reason}`, 'LIVE_INSPECTION_FAILED');
+    this.target = target;
+  }
+}
+
+export class NoFindingsError extends SowError {
+  constructor(source) {
+    super(`No audit findings available from ${source}. Production SOW generation requires authoritative findings. (Use --sample to generate non-contractual demonstration SOW)`, 'NO_FINDINGS');
+  }
+}
+
+export class NoAdmissibleRequirementsError extends SowError {
+  constructor(totalEvaluated, refusalCount) {
+    super(`Scope admissibility gate refused all ${totalEvaluated} findings (${refusalCount} refused). Zero contractable requirements remain.`, 'NO_ADMISSIBLE_REQUIREMENTS');
+  }
+}
+
+export class BudgetCalculationError extends SowError {
+  constructor(message) {
+    super(message, 'INVALID_COMMERCIAL_TERMS');
+  }
+}
+
+export class SowInvariantError extends SowError {
+  constructor(message) {
+    super(`SOW invariant failure: ${message}`, 'INVARIANT_VIOLATION');
+  }
+}
+
+export const SOW_CURRENCY = 'USD';
+export const SOW_CURRENCY_MINOR_EXPONENT = 2;
+
+/**
+ * Parse commercial budget into integer minor units (cents) and major units (USD).
+ * Ensures money units are unambiguous and rejects invalid, negative, or sub-cent fractional budgets.
+ */
+export function parseCommercialBudget({ budget = 45000, budgetMinor = null } = {}) {
+  if (budgetMinor !== null && budgetMinor !== undefined) {
+    if (!Number.isInteger(budgetMinor) || budgetMinor < 0) {
+      throw new BudgetCalculationError(`budgetMinor must be a non-negative integer (cents), got: ${budgetMinor}`);
+    }
+    const feeUsd = Number((budgetMinor / 100).toFixed(2));
+    return {
+      feeMinor: budgetMinor,
+      feeUsd,
+      currency: SOW_CURRENCY,
+      minorUnitExponent: SOW_CURRENCY_MINOR_EXPONENT,
+    };
+  }
+
+  const num = Number(budget);
+  if (Number.isNaN(num) || !Number.isFinite(num) || num < 0) {
+    throw new BudgetCalculationError(`Commercial budget must be a non-negative number, got: ${budget}`);
+  }
+
+  const minorUnits = Math.round(num * 100);
+  if (Math.abs(num * 100 - minorUnits) > 1e-6) {
+    throw new BudgetCalculationError(`Commercial budget cannot contain fractional minor units (sub-cents): ${budget}`);
+  }
+
+  const feeUsd = Number((minorUnits / 100).toFixed(2));
+  return {
+    feeMinor: minorUnits,
+    feeUsd,
+    currency: SOW_CURRENCY,
+    minorUnitExponent: SOW_CURRENCY_MINOR_EXPONENT,
+  };
+}
+
+/**
+ * Exact integer milestone fee allocation distributing remainder deterministically.
+ * Allocates integer currency units (such as minor units / cents) across work packages without remainder leaks.
+ */
+export function allocateMilestoneFees(totalUnits, count) {
+  if (!Number.isInteger(totalUnits) || totalUnits < 0) {
+    throw new BudgetCalculationError(`Commercial budget units must be a non-negative integer, got: ${totalUnits}`);
+  }
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new BudgetCalculationError(`Cannot allocate milestone fees across ${count} work packages`);
+  }
+  const base = Math.floor(totalUnits / count);
+  const remainder = totalUnits - (base * count);
+  const fees = [];
+  for (let i = 0; i < count; i++) {
+    fees.push(base + (i < remainder ? 1 : 0));
+  }
+  const sum = fees.reduce((acc, f) => acc + f, 0);
+  if (sum !== totalUnits) {
+    throw new BudgetCalculationError(`Milestone fee sum (${sum}) does not equal total units (${totalUnits})`);
+  }
+  return fees;
+}
+
+export { getCanonicalRunTimestamp, sortRunCandidatesChronologically };
+
+/**
+ * Verify cross-object runtime invariants before SOW export
+ */
+export function validateSowInvariants(sow) {
+  if (!sow || typeof sow !== 'object') {
+    throw new SowInvariantError('SOW root must be an object');
+  }
+  if (!['CONTRACTUAL', 'DRAFT', 'NON_CONTRACTUAL_SAMPLE'].includes(sow.generation_mode)) {
+    throw new SowInvariantError(`Invalid generation_mode: ${sow.generation_mode}`);
+  }
+  if (sow.generation_mode === 'CONTRACTUAL' && sow.synthetic_evidence) {
+    throw new SowInvariantError('Contractual SOW cannot contain synthetic evidence');
+  }
+  if (sow.currency !== 'USD') {
+    throw new SowInvariantError(`Currency must be 'USD', got: ${sow.currency}`);
+  }
+  if (sow.currency_minor_unit_exponent !== 2) {
+    throw new SowInvariantError(`Minor unit exponent must be 2, got: ${sow.currency_minor_unit_exponent}`);
+  }
+  if (typeof sow.commercial_total_fee_minor !== 'number' || !Number.isInteger(sow.commercial_total_fee_minor)) {
+    throw new SowInvariantError(`commercial_total_fee_minor must be an integer, got: ${sow.commercial_total_fee_minor}`);
+  }
+  if (typeof sow.commercial_total_fee_usd !== 'number' || sow.commercial_total_fee_usd < 0) {
+    throw new SowInvariantError(`commercial_total_fee_usd must be a non-negative number, got: ${sow.commercial_total_fee_usd}`);
+  }
+  if (sow.commercial_total_fee_minor !== Math.round(sow.commercial_total_fee_usd * 100)) {
+    throw new SowInvariantError(`commercial_total_fee_minor (${sow.commercial_total_fee_minor}) does not match commercial_total_fee_usd (${sow.commercial_total_fee_usd})`);
+  }
+  if (!Array.isArray(sow.work_packages) || sow.work_packages.length === 0) {
+    throw new SowInvariantError('SOW must contain at least one work package');
+  }
+  if (!Array.isArray(sow.deliverables) || sow.deliverables.length === 0) {
+    throw new SowInvariantError('SOW must contain at least one deliverable');
+  }
+  if (sow.work_packages.length !== sow.deliverables.length) {
+    throw new SowInvariantError(`Work packages count (${sow.work_packages.length}) must match deliverables count (${sow.deliverables.length})`);
+  }
+  if (!Array.isArray(sow.traceability_matrix) || sow.traceability_matrix.length === 0) {
+    throw new SowInvariantError('SOW must contain at least one traceability matrix requirement');
+  }
+  const wpIds = new Set(sow.work_packages.map((wp) => wp.work_package_id));
+  const delivIds = new Set(sow.deliverables.map((d) => d.deliverable_id));
+  const seenReqIds = new Set();
+  const seenFindingKeys = new Set();
+  for (const row of sow.traceability_matrix) {
+    if (!wpIds.has(row.work_package_id)) {
+      throw new SowInvariantError(`Traceability matrix references unknown work package: ${row.work_package_id}`);
+    }
+    if (!delivIds.has(row.deliverable_id)) {
+      throw new SowInvariantError(`Traceability matrix references unknown deliverable: ${row.deliverable_id}`);
+    }
+    if (!Array.isArray(row.evidence_ids) || row.evidence_ids.length === 0) {
+      throw new SowInvariantError(`Traceability matrix row ${row.sow_requirement_id} lacks supporting evidence_ids`);
+    }
+    if (seenReqIds.has(row.sow_requirement_id)) {
+      throw new SowInvariantError(`Duplicate sow_requirement_id in traceability matrix: ${row.sow_requirement_id}`);
+    }
+    seenReqIds.add(row.sow_requirement_id);
+    const findingKey = `${row.finding_id}:${row.target_subject || ''}`;
+    if (seenFindingKeys.has(findingKey)) {
+      throw new SowInvariantError(`Duplicate finding_id and subject in traceability matrix: ${findingKey}`);
+    }
+    seenFindingKeys.add(findingKey);
+  }
+
+  const milestones = sow.delivery_schedule?.milestones || [];
+  const milestoneMinorSum = milestones.reduce((sum, m) => sum + m.fee_minor, 0);
+  if (milestoneMinorSum !== sow.commercial_total_fee_minor) {
+    throw new SowInvariantError(`Milestone minor fees sum (${milestoneMinorSum}) does not match total minor fee (${sow.commercial_total_fee_minor})`);
+  }
+  const milestoneUsdSum = Number(milestones.reduce((sum, m) => sum + m.fee_usd, 0).toFixed(2));
+  if (milestoneUsdSum !== sow.commercial_total_fee_usd) {
+    throw new SowInvariantError(`Milestone USD fees sum (${milestoneUsdSum}) does not match total fee USD (${sow.commercial_total_fee_usd})`);
+  }
+  for (const m of milestones) {
+    if (m.fee_minor !== Math.round(m.fee_usd * 100)) {
+      throw new SowInvariantError(`Milestone ${m.milestone_id} fee_minor (${m.fee_minor}) does not match fee_usd (${m.fee_usd})`);
+    }
+  }
+
+  const gate = sow.admissibility_gate;
+  if (gate.total_findings_evaluated !== gate.admitted_count + gate.refused_count) {
+    throw new SowInvariantError(`Admissibility gate numbers do not balance: ${gate.total_findings_evaluated} != ${gate.admitted_count} + ${gate.refused_count}`);
+  }
+  return true;
+}
+
+/**
+ * Standard synthetic baseline findings used strictly for sample mode (--sample / --demo)
+ */
+export function getSampleBaselineFindings() {
+  return [
+    {
+      finding_id: 'F-TECH-CWV-001',
+      detector_id: 'TECH-001',
+      discipline: ['technical'],
+      classification: { severity: 'critical', confidence: 'deterministic' },
+      subject: { identifier: 'https://example.test/', url: 'https://example.test/' },
+      observation: { summary: 'Render-blocking JavaScript bundle degrades Mobile LCP to 4.2s', evidence: ['EVD-CWV-001'] },
+      remediation: { preferred: 'Implement asynchronous resource loading and preconnect headers' },
+      verification: { detector_to_rerun: 'TECH-001', method: 'Static CWV inspection and HTTP header probe' },
+      ice_score: 14.5,
+    },
+    {
+      finding_id: 'F-CRO-AUTO-007',
+      detector_id: 'CRO-007',
+      discipline: ['cro'],
+      classification: { severity: 'high', confidence: 'deterministic' },
+      subject: { identifier: 'https://example.test/checkout', url: 'https://example.test/checkout' },
+      observation: { summary: 'Checkout form inputs lack HTML5 autocomplete attributes, increasing manual mobile entry by 68%', evidence: ['EVD-CRO-007'] },
+      remediation: { preferred: 'Inject standard autocomplete attributes (autocomplete="email", autocomplete="name", autocomplete="tel")' },
+      verification: { detector_to_rerun: 'CRO-007', method: 'DOM inspection and AST patch verification' },
+      ice_score: 18.0,
+    },
+    {
+      finding_id: 'F-CRO-DIST-013',
+      detector_id: 'CRO-013',
+      discipline: ['cro'],
+      classification: { severity: 'high', confidence: 'deterministic' },
+      subject: { identifier: 'https://example.test/checkout', url: 'https://example.test/checkout' },
+      observation: { summary: 'Dedicated checkout funnel contains 14 external header navigation links creating distraction leaks', evidence: ['EVD-CRO-013'] },
+      remediation: { preferred: 'Deploy enclosed distraction-free checkout layout stripping non-essential navigation' },
+      verification: { detector_to_rerun: 'CRO-013', method: 'Navigation link count verification' },
+      ice_score: 12.0,
+    },
+    {
+      finding_id: 'F-ANS-PRIC-001',
+      detector_id: 'ANS-001',
+      discipline: ['aeo'],
+      classification: { severity: 'high', confidence: 'deterministic' },
+      subject: { identifier: 'https://example.test/saas/pricing.html', url: 'https://example.test/saas/pricing.html' },
+      observation: { summary: 'Commercial pricing questions lack direct-extract definition passages under 75 words', evidence: ['EVD-ANS-001'] },
+      remediation: { preferred: 'Restructure FAQ headings with immediate concise copular answer passages' },
+      verification: { detector_to_rerun: 'ANS-001', method: 'Passage length and question-answer extraction test' },
+      ice_score: 11.0,
+    },
+    {
+      finding_id: 'F-SCHEMA-FAQ-001',
+      detector_id: 'SCHEMA-001',
+      discipline: ['schema'],
+      classification: { severity: 'medium', confidence: 'deterministic' },
+      subject: { identifier: 'https://example.test/pricing', url: 'https://example.test/pricing' },
+      observation: { summary: 'Commercial FAQ content lacks FAQPage JSON-LD schema markup', evidence: ['EVD-SCH-001'] },
+      remediation: { preferred: 'Deploy validated Schema.org FAQPage structured data' },
+      verification: { detector_to_rerun: 'SCHEMA-001', method: 'JSON-LD schema validation gate' },
+      ice_score: 9.5,
+    },
+    {
+      finding_id: 'F-EXP-GEO-999',
+      detector_id: 'EXP-GEO-999',
+      discipline: ['geo'],
+      classification: { severity: 'low', confidence: 'experimental', finding_type: 'experimental' },
+      subject: { identifier: 'https://unrelated-blog.test/post-1', url: 'https://unrelated-blog.test/post-1' },
+      observation: { summary: 'Speculative model hallucination on third-party forum', evidence: [] },
+      remediation: { preferred: 'Consult external legal counsel regarding public forum sentiment' },
+      ice_score: 2.0,
+    },
+  ];
+}
 
 /**
  * Generate an Enterprise-Grade Statement of Work (SOW) from SEO, AEO, GEO, SERP, and CRO findings.
- * Forces strict traceability: Evidence -> Obligation -> Acceptance Test.
+ * Forces strict downward traceability: Evidence -> Obligation -> Acceptance Test.
  */
 export async function generateSow(root, {
   target,
   baseUrl,
   refDate,
   runId,
+  live = false,
+  sample = false,
+  demo = false,
+  draft = false,
+  findings: inputFindings = null,
   client = 'Acme Corporation',
   clientContact = 'client-procurement@acme.test',
   supplier = 'Nebula Components & Citable Practice',
   supplierContact = 'advisory@nebulacomponents.test',
   budget = 45000,
+  budgetMinor = null,
   termDays = 90,
   inScopeProperties = [],
+  scopeMode = 'HOST_AND_SUBDOMAINS',
   minIceScore = 8.0,
+  allowedDisciplines = ['seo', 'aeo', 'geo', 'technical', 'schema', 'entity', 'cro'],
+  allowExperimental = false,
+  excludedDetectors = [],
+  roleMapping = null,
   sowId = null,
 } = {}) {
   const generatedAt = nowIso();
   const sowIdentifier = sowId || `SOW-${Date.now().toString(36).toUpperCase()}`;
+  const isSample = Boolean(sample || demo);
+  const isDraft = Boolean(draft);
+  const generationMode = isSample ? 'NON_CONTRACTUAL_SAMPLE' : (isDraft ? 'DRAFT' : 'CONTRACTUAL');
 
   let findings = [];
-  let sitePages = [];
-
-  // Attempt building live or target context if target provided
-  if (target) {
-    try {
-      const ctx = await buildContext(root, { target, baseUrl, refDate });
-      if (ctx?.site) {
-        sitePages = indexTargets(ctx);
-        const detectors = selectDetectors({ scopes: ['technical', 'seo', 'aeo', 'geo', 'schema', 'entity'] });
-        const res = runDetectors(detectors, ctx);
-        findings = res.findings;
-      }
-    } catch (e) {
-      // Non-blocking fallback
+  let sourceProvenance = {
+    source_type: null,
+    source_identifier: null,
+    findings_count: 0,
+    integrity_hash: null,
+  };
+
+  let resolved;
+  try {
+    resolved = await resolveEvidenceSource(root, {
+      findings: inputFindings,
+      runId,
+      target,
+      live,
+      baseUrl,
+      refDate,
+      sample,
+      demo,
+      draft,
+      scopes: ['technical', 'seo', 'aeo', 'geo', 'schema', 'entity', 'cro'],
+    });
+  } catch (err) {
+    if (err.code === 'RUN_NOT_FOUND') {
+      throw new RunNotFoundError(runId);
+    }
+    if (err.code === 'FINDINGS_MISSING') {
+      throw new FindingsMissingError(runId, err.details?.filePath);
+    }
+    if (err.code === 'FINDINGS_INVALID') {
+      throw new FindingsInvalidError(runId, err.message);
+    }
+    if (err.code === 'LIVE_INSPECTION_FAILED') {
+      throw new LiveInspectionFailedError(target, err.message);
     }
+    if (err.code === 'NO_FINDINGS') {
+      const srcDesc = target ? `live target "${target}"` : (runId ? `run "${runId}"` : 'local workspace');
+      throw new NoFindingsError(srcDesc);
+    }
+    throw err;
   }
 
-  // If runId provided or prior runs exist in .citable/runs, load recorded evidence
-  const runsDir = path.join(root, '.citable', 'runs');
-  let loadedRunId = runId;
-  if (!loadedRunId && fs.existsSync(runsDir)) {
-    const runs = fs.readdirSync(runsDir).filter((d) => !d.startsWith('.'));
-    if (runs.length > 0) loadedRunId = runs[runs.length - 1];
+  findings = resolved.findings;
+  sourceProvenance = {
+    source_type: resolved.source_type,
+    source_identifier: resolved.source_identifier,
+    findings_count: resolved.findings_count,
+    integrity_hash: resolved.integrity_hash,
+  };
+
+  // If no findings were discovered:
+  if (!Array.isArray(findings) || findings.length === 0) {
+    if (isSample) {
+      findings = getSampleBaselineFindings();
+      sourceProvenance.source_type = 'SAMPLE_BASELINE';
+      sourceProvenance.source_identifier = 'citable://samples/enterprise-baseline';
+      sourceProvenance.findings_count = findings.length;
+    } else {
+      const srcDesc = target ? `live target "${target}"` : (runId ? `run "${runId}"` : 'local workspace');
+      throw new NoFindingsError(srcDesc);
+    }
   }
 
-  if (loadedRunId) {
-    const runPath = path.join(runsDir, loadedRunId);
-    const findPath = path.join(runPath, 'findings.json');
-    if (fs.existsSync(findPath) && findings.length === 0) {
-      try { findings = readJson(findPath); } catch {}
+  if (generationMode === 'CONTRACTUAL') {
+    if (!client || typeof client !== 'string' || client.trim() === '') {
+      throw new SowError('Contractual SOW requires explicit client name', 'INVALID_COMMERCIAL_TERMS');
+    }
+    if (budget === null && budgetMinor === null) {
+      throw new SowError('Contractual SOW requires explicit budget or budgetMinor', 'INVALID_COMMERCIAL_TERMS');
+    }
+    if (!termDays || termDays <= 0 || !Number.isFinite(termDays)) {
+      throw new SowError('Contractual SOW requires positive finite termDays', 'INVALID_COMMERCIAL_TERMS');
     }
   }
 
-  // If no findings exist from live run, supply standard baseline audit findings for SOW generation
-  if (findings.length === 0) {
-    findings = [
-      {
-        detector_id: 'TECH-001',
-        discipline: ['technical'],
-        classification: { severity: 'critical', confidence: 'deterministic' },
-        subject: { identifier: 'https://example.test/', url: 'https://example.test/' },
-        observation: { summary: 'Render-blocking JavaScript bundle degrades Mobile LCP to 4.2s', evidence: ['EVD-CWV-001'] },
-        remediation: { preferred: 'Implement asynchronous resource loading and preconnect headers' },
-        verification: { detector_to_rerun: 'TECH-001', method: 'Static CWV inspection and HTTP header probe' },
-        ice_score: 14.5,
-      },
-      {
-        detector_id: 'CRO-007',
-        discipline: ['cro'],
-        classification: { severity: 'high', confidence: 'deterministic' },
-        subject: { identifier: 'https://example.test/checkout', url: 'https://example.test/checkout' },
-        observation: { summary: 'Checkout form inputs lack HTML5 autocomplete attributes, increasing manual mobile entry by 68%', evidence: ['EVD-CRO-007'] },
-        remediation: { preferred: 'Inject standard autocomplete attributes (autocomplete="email", autocomplete="name", autocomplete="tel")' },
-        verification: { detector_to_rerun: 'CRO-007', method: 'DOM inspection and AST patch verification' },
-        ice_score: 18.0,
-      },
-      {
-        detector_id: 'CRO-013',
-        discipline: ['cro'],
-        classification: { severity: 'high', confidence: 'deterministic' },
-        subject: { identifier: 'https://example.test/checkout', url: 'https://example.test/checkout' },
-        observation: { summary: 'Dedicated checkout funnel contains 14 external header navigation links creating distraction leaks', evidence: ['EVD-CRO-013'] },
-        remediation: { preferred: 'Deploy enclosed distraction-free checkout layout stripping non-essential navigation' },
-        verification: { detector_to_rerun: 'CRO-013', method: 'Navigation link count verification' },
-        ice_score: 12.0,
-      },
-      {
-        detector_id: 'ANS-001',
-        discipline: ['aeo'],
-        classification: { severity: 'high', confidence: 'deterministic' },
-        subject: { identifier: 'https://example.test/saas/pricing.html', url: 'https://example.test/saas/pricing.html' },
-        observation: { summary: 'Commercial pricing questions lack direct-extract definition passages under 75 words', evidence: ['EVD-ANS-001'] },
-        remediation: { preferred: 'Restructure FAQ headings with immediate concise copular answer passages' },
-        verification: { detector_to_rerun: 'ANS-001', method: 'Passage length and question-answer extraction test' },
-        ice_score: 11.0,
-      },
-      {
-        detector_id: 'SCHEMA-001',
-        discipline: ['schema'],
-        classification: { severity: 'medium', confidence: 'deterministic' },
-        subject: { identifier: 'https://example.test/pricing', url: 'https://example.test/pricing' },
-        observation: { summary: 'Commercial FAQ content lacks FAQPage JSON-LD schema markup', evidence: ['EVD-SCH-001'] },
-        remediation: { preferred: 'Deploy validated Schema.org FAQPage structured data' },
-        verification: { detector_to_rerun: 'SCHEMA-001', method: 'JSON-LD schema validation gate' },
-        ice_score: 9.5,
-      },
-      // Inadmissible exploratory finding (for demonstrating the gate)
-      {
-        detector_id: 'EXP-GEO-999',
-        discipline: ['geo'],
-        classification: { severity: 'low', confidence: 'experimental', finding_type: 'experimental' },
-        subject: { identifier: 'https://unrelated-blog.test/post-1', url: 'https://unrelated-blog.test/post-1' },
-        observation: { summary: 'Speculative model hallucination on third-party forum', evidence: [] },
-        remediation: { preferred: 'Consult external legal counsel regarding public forum sentiment' },
-        ice_score: 2.0,
-      },
-    ];
-  }
-
-  const effectiveScopeProps = inScopeProperties.length > 0
-    ? inScopeProperties
-    : [baseUrl || 'https://example.test'];
+  let effectiveScopeProps = inScopeProperties.length > 0 ? [...inScopeProperties] : [];
+  if (effectiveScopeProps.length === 0) {
+    if (baseUrl) {
+      effectiveScopeProps.push(baseUrl);
+    } else if (target && typeof target === 'string' && target.startsWith('http')) {
+      effectiveScopeProps.push(target);
+    } else if (isSample) {
+      effectiveScopeProps.push('https://example.test');
+    } else {
+      // Derive from finding subjects
+      for (const f of findings) {
+        const s = f.subject?.identifier || f.subject?.url || (typeof f.subject === 'string' ? f.subject : null);
+        if (s) {
+          try {
+            const u = new URL(s.includes('://') ? s : `https://${s}`);
+            if (!effectiveScopeProps.includes(u.origin)) {
+              effectiveScopeProps.push(u.origin);
+            }
+          } catch {}
+        }
+      }
+    }
+  }
+
+  if (generationMode === 'CONTRACTUAL' && effectiveScopeProps.length === 0) {
+    throw new SowError('Contractual SOW requires explicit inScopeProperties or derivable target properties', 'SCOPE_REQUIRED');
+  }
 
   // -------------------------------------------------------------
-  // THE ADMISSIBILITY GATE (Filter findings to contractual scope)
+  // THE ADMISSIBILITY GATE (Filter findings into contractual scope)
   // -------------------------------------------------------------
   const gateResult = evaluateScopeAdmissibility(findings, {
     inScopeProperties: effectiveScopeProps,
+    scopeMode,
     minIceScore,
+    allowedDisciplines,
+    allowExperimental,
+    excludedDetectors,
+    roleMapping,
+    rejectTemplateDefaultOwner: generationMode === 'CONTRACTUAL',
   });
 
   const admitted = gateResult.admitted_requirements;
+  if (admitted.length === 0) {
+    throw new NoAdmissibleRequirementsError(findings.length, gateResult.refusal_log.length);
+  }
 
   // Group admitted requirements into Work Packages
   const wpMap = new Map();
@@ -162,20 +487,25 @@ export async function generateSow(root, {
   // Mapping Finding -> Recommendation -> SOW Requirement -> Deliverable -> Acceptance Test -> Owner -> Evidence
   const traceabilityMatrix = admitted.map((item) => ({
     finding_id: item.finding_id,
+    detector_id: item.detector_id,
     recommendation: item.recommendation,
     sow_requirement_id: item.sow_requirement_id,
     work_package_id: item.work_package_id,
     deliverable_id: item.deliverable_id,
     acceptance_test_id: item.acceptance_test_id,
     owner: item.owner,
+    owner_source: item.owner_source,
+    owner_mapping_version: item.owner_mapping_version,
     evidence_id: item.evidence_id,
+    evidence_ids: item.evidence_ids,
     severity: item.severity,
     target_subject: item.subject,
     acceptance_criteria: item.acceptance_test,
+    acceptance_basis: item.acceptance_basis || 'automated_detector_rerun',
   }));
 
   // Deliverables definitions
-  const deliverables = workPackages.map((wp, idx) => ({
+  const deliverables = workPackages.map((wp) => ({
     deliverable_id: wp.deliverable_id,
     work_package_id: wp.work_package_id,
     title: `${wp.name} Implementation & Verification Package`,
@@ -195,27 +525,41 @@ export async function generateSow(root, {
     evidence_required: `Deterministic before-and-after observation JSON matching ${item.evidence_id}`,
   }));
 
-  // Commercial structure
-  const feePerWp = Math.round(budget / (workPackages.length || 1));
+  // Commercial structure with deterministic integer minor-unit arithmetic
+  const { feeMinor, feeUsd, currency, minorUnitExponent } = parseCommercialBudget({ budget, budgetMinor });
+  const milestoneFeesMinor = allocateMilestoneFees(feeMinor, workPackages.length);
+  const milestoneFeesUsd = milestoneFeesMinor.map((m) => Number((m / 100).toFixed(2)));
   const commercialMilestones = workPackages.map((wp, idx) => ({
     milestone_id: `MILESTONE-0${idx + 1}`,
     work_package_id: wp.work_package_id,
     name: wp.name,
-    fee_usd: feePerWp,
+    fee_minor: milestoneFeesMinor[idx],
+    fee_usd: milestoneFeesUsd[idx],
     billing_trigger: `Successful customer acceptance sign-off of Deliverable ${wp.deliverable_id}`,
     target_delivery_week: (idx + 1) * 3,
   }));
 
+  const sowTitle = isSample
+    ? 'Statement of Work: Enterprise Search & Conversion Intelligence Engineering [DEMONSTRATION SAMPLE]'
+    : (isDraft
+      ? 'Statement of Work: Enterprise Search & Conversion Intelligence Engineering [DRAFT]'
+      : 'Statement of Work: Enterprise Search & Conversion Intelligence Engineering');
+
   const sow = {
     $schema: 'citable://schemas/sow.schema.json',
     sow_id: sowIdentifier,
     version: '1.0.0',
-    title: `Statement of Work: Enterprise Search & Conversion Intelligence Engineering`,
+    generation_mode: generationMode,
+    title: sowTitle,
+    synthetic_evidence: isSample,
     client: { name: client, contact: clientContact },
     supplier: { name: supplier, contact: supplierContact },
     effective_date: generatedAt.split('T')[0],
     term_days: termDays,
-    commercial_total_fee_usd: budget,
+    currency,
+    currency_minor_unit_exponent: minorUnitExponent,
+    commercial_total_fee_minor: feeMinor,
+    commercial_total_fee_usd: feeUsd,
 
     // Pillar 1: Executive Scope Statement
     executive_scope: {
@@ -373,7 +717,9 @@ export async function generateSow(root, {
 
     // Pillar 20: Commercial Structure
     commercial_terms: {
-      total_fixed_fee_usd: budget,
+      total_fixed_fee_minor: feeMinor,
+      total_fixed_fee_usd: feeUsd,
+      currency,
       payment_terms: 'Net 30 upon verified deliverable acceptance',
       milestones: commercialMilestones,
     },
@@ -413,8 +759,22 @@ export async function generateSow(root, {
 
     // Pillar 25: The Final Traceability Matrix
     traceability_matrix: traceabilityMatrix,
+
+    // Machine-readable Provenance Envelope
+    generation_provenance: {
+      generated_at: generatedAt,
+      generator_version: '1.18.2',
+      generation_mode: generationMode,
+      source_type: sourceProvenance.source_type || 'UNKNOWN',
+      source_identifier: sourceProvenance.source_identifier || null,
+      source_findings_count: sourceProvenance.findings_count,
+      findings_integrity_hash: sourceProvenance.integrity_hash || null,
+      synthetic_evidence: isSample,
+    },
   };
 
+  validateSowInvariants(sow);
+
   return sow;
 }
 
@@ -422,16 +782,23 @@ export async function generateSow(root, {
  * Render Statement of Work as GitHub-flavored Markdown
  */
 export function renderSowMarkdown(sow) {
+  const modeBanner = sow.generation_mode === 'NON_CONTRACTUAL_SAMPLE'
+    ? '> ⚠️ **NON-CONTRACTUAL DEMONSTRATION SAMPLE**: This document was generated with synthetic audit baseline findings for evaluation and demonstration purposes. It does NOT represent a binding contractual obligation or live audit evidence.'
+    : (sow.generation_mode === 'DRAFT'
+      ? '> 📝 **DRAFT STATEMENT OF WORK**: This preliminary draft contains unfinalized engagement terms and requirements. Final executive approval required prior to signature.'
+      : '> **Contractual Principle**: This Statement of Work forces strict downward traceability from documented audit evidence to contractual obligation, and from obligation to verifiable acceptance. Findings are admitted strictly through a formal Admissibility Gate. In adherence to Citable governance principles, **no search rankings, AI citations, or conversion revenues are guaranteed**; fees are tied exclusively to objective deliverable acceptance.');
+
   const lines = [
     `# ${sow.title}`,
     `====================================================================`,
-    `- **SOW ID**: \`${sow.sow_id}\` | **Version**: \`${sow.version}\``,
+    `- **SOW ID**: \`${sow.sow_id}\` | **Version**: \`${sow.version}\` | **Mode**: \`${sow.generation_mode}\``,
     `- **Client**: **${sow.client.name}** (${sow.client.contact})`,
     `- **Supplier**: **${sow.supplier.name}** (${sow.supplier.contact})`,
     `- **Effective Date**: \`${sow.effective_date}\` | **Term**: \`${sow.term_days} calendar days\``,
-    `- **Commercial Total**: **$${sow.commercial_total_fee_usd.toLocaleString()} USD**`,
+    `- **Commercial Total**: **$${sow.commercial_total_fee_usd.toLocaleString('en-US', { minimumFractionDigits: (sow.commercial_total_fee_minor % 100 === 0) ? 0 : 2, maximumFractionDigits: 2 })} USD**`,
+    `- **Audit Source**: \`${sow.generation_provenance.source_type}\` (${sow.generation_provenance.source_identifier || 'N/A'}) | **Generator**: \`v${sow.generation_provenance.generator_version}\``,
     ``,
-    `> **Contractual Principle**: This Statement of Work forces strict downward traceability from documented audit evidence to contractual obligation, and from obligation to verifiable acceptance. Findings are admitted strictly through a formal Admissibility Gate. In adherence to Citable governance principles, **no search rankings, AI citations, or conversion revenues are guaranteed**; fees are tied exclusively to objective deliverable acceptance.`,
+    modeBanner,
     ``,
     `---`,
     `## 1. Executive Scope Statement`,
@@ -505,7 +872,7 @@ export function renderSowMarkdown(sow) {
     `## 12. Delivery Sequencing & Milestone Schedule`,
     `| Milestone | Work Package | Target Week | Fee (USD) | Acceptance Trigger |`,
     `| :--- | :--- | :--- | :--- | :--- |`,
-    ...sow.delivery_schedule.milestones.map((m) => `| **${m.milestone_id}** | \`${m.work_package_id}\` | Week ${m.target_delivery_week} | **$${m.fee_usd.toLocaleString()}** | ${m.billing_trigger} |`),
+    ...sow.delivery_schedule.milestones.map((m) => `| **${m.milestone_id}** | \`${m.work_package_id}\` | Week ${m.target_delivery_week} | **$${m.fee_usd.toLocaleString('en-US', { minimumFractionDigits: (m.fee_minor % 100 === 0) ? 0 : 2, maximumFractionDigits: 2 })}** | ${m.billing_trigger} |`),
     ``,
     `## 13. Scope Change-Control Process`,
     `- **Procedure**: ${sow.change_control_process.procedure}`,
@@ -537,7 +904,7 @@ export function renderSowMarkdown(sow) {
     `- **Decision Records**: ${sow.governance_model.decision_logging}`,
     ``,
     `## 20. Commercial Terms & Payment Schedule`,
-    `- **Total Contract Value**: **$${sow.commercial_terms.total_fixed_fee_usd.toLocaleString()} USD**`,
+    `- **Total Contract Value**: **$${sow.commercial_terms.total_fixed_fee_usd.toLocaleString('en-US', { minimumFractionDigits: (sow.commercial_terms.total_fixed_fee_minor % 100 === 0) ? 0 : 2, maximumFractionDigits: 2 })} USD**`,
     `- **Terms**: ${sow.commercial_terms.payment_terms}`,
     ``,
     `## 21. Explicit Out-of-Scope Declarations`,
@@ -563,7 +930,7 @@ export function renderSowMarkdown(sow) {
     ``,
     `| Finding ID | Recommendation | SOW Req ID | Deliverable ID | Acceptance Test ID | Responsible Owner | Source Evidence |`,
     `| :--- | :--- | :--- | :--- | :--- | :--- | :--- |`,
-    ...sow.traceability_matrix.map((t) => `| **\`${t.finding_id}\`** | ${t.recommendation.slice(0, 45)}... | **\`${t.sow_requirement_id}\`** | \`${t.deliverable_id}\` | \`${t.acceptance_test_id}\` | ${t.owner} | \`${t.evidence_id}\` |`),
+    ...sow.traceability_matrix.map((t) => `| **\`${t.finding_id}\`** | ${t.recommendation.slice(0, 45)}... | **\`${t.sow_requirement_id}\`** | \`${t.deliverable_id}\` | \`${t.acceptance_test_id}\` | ${t.owner} | \`${t.evidence_ids?.join(', ') || t.evidence_id}\` |`),
     ``,
     `---`,
     `### Contract Execution & Authorization`,
@@ -583,18 +950,27 @@ export function renderSowMarkdown(sow) {
  * Render Statement of Work as Standalone Enterprise HTML
  */
 export function renderSowHtml(sow) {
+  const isSample = sow.generation_mode === 'NON_CONTRACTUAL_SAMPLE';
+  const isDraft = sow.generation_mode === 'DRAFT';
+  const badgeColor = isSample ? 'var(--warning)' : (isDraft ? 'var(--accent)' : 'var(--success)');
+  const modeNotice = isSample
+    ? '<div class="disclosure" style="border-left-color:var(--warning); background:rgba(210,153,34,0.15);"><strong style="color:var(--warning);">DEMONSTRATION SAMPLE NOTICE:</strong> This Statement of Work contains synthetic audit baseline findings for evaluation and demonstration purposes. It does NOT represent a binding contractual obligation or live audit evidence.</div>'
+    : (isDraft
+      ? '<div class="disclosure"><strong style="color:var(--accent);">DRAFT ENGAGEMENT NOTICE:</strong> This document represents a preliminary draft with unfinalized commercial parameters. Final executive sign-off required prior to contract binding.</div>'
+      : '<div class="disclosure"><strong>Enterprise Statement of Work Governance Notice:</strong> This agreement binds supplier fees exclusively to verified deliverable acceptance and closed-loop test execution. In compliance with Citable governance standards, <strong>no search engine ranking, AI citation presence, or commercial conversion revenue outcomes are guaranteed</strong>.</div>');
+
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <title>${sow.title} - ${sow.sow_id}</title>
+  <title>${escapeHtml(sow.title)} - ${escapeHtml(sow.sow_id)}</title>
   <style>
     :root { --bg: #0d1117; --card: #161b22; --border: #30363d; --text: #c9d1d9; --accent: #58a6ff; --danger: #f85149; --warning: #d29922; --success: #3fb950; }
     body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; margin: 0; padding: 40px 20px; }
     .container { max-width: 1180px; margin: 0 auto; }
     header { border-bottom: 2px solid var(--border); padding-bottom: 24px; margin-bottom: 32px; }
     h1 { font-size: 28px; margin: 0 0 10px 0; color: #fff; }
-    .sow-badge { background: #1f6feb; color: #fff; padding: 4px 10px; border-radius: 4px; font-size: 13px; font-weight: bold; }
+    .sow-badge { background: ${badgeColor}; color: #000; padding: 4px 10px; border-radius: 4px; font-size: 13px; font-weight: bold; }
     .meta-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin: 24px 0; }
     .card { background: var(--card); border: 1px solid var(--border); border-radius: 6px; padding: 18px; }
     .card-val { font-size: 26px; font-weight: bold; color: #fff; margin-top: 4px; }
@@ -615,20 +991,21 @@ export function renderSowHtml(sow) {
   <div class="container">
     <header>
       <div style="display:flex; justify-content:space-between; align-items:center;">
-        <h1>${sow.title}</h1>
-        <span class="sow-badge">${sow.sow_id}</span>
+        <h1>${escapeHtml(sow.title)}</h1>
+        <div>
+          <span class="sow-badge">${escapeHtml(sow.generation_mode)}</span>
+          <span class="sow-badge" style="background:#1f6feb; color:#fff; margin-left:8px;">${escapeHtml(sow.sow_id)}</span>
+        </div>
       </div>
       <div style="color:#8b949e; font-size:14px; margin-top:8px;">
-        Client: <strong>${sow.client.name}</strong> &nbsp;|&nbsp; Supplier: <strong>${sow.supplier.name}</strong> &nbsp;|&nbsp; Term: <strong>${sow.term_days} Days</strong> &nbsp;|&nbsp; Effective: <strong>${sow.effective_date}</strong>
+        Client: <strong>${escapeHtml(sow.client.name)}</strong> &nbsp;|&nbsp; Supplier: <strong>${escapeHtml(sow.supplier.name)}</strong> &nbsp;|&nbsp; Term: <strong>${escapeHtml(String(sow.term_days))} Days</strong> &nbsp;|&nbsp; Effective: <strong>${escapeHtml(sow.effective_date)}</strong> &nbsp;|&nbsp; Source: <strong>${escapeHtml(sow.generation_provenance.source_type)}</strong>
       </div>
     </header>
 
-    <div class="disclosure">
-      <strong>Enterprise Statement of Work Governance Notice:</strong> This agreement binds supplier fees exclusively to verified deliverable acceptance and closed-loop test execution. In compliance with Citable governance standards, <strong>no search engine ranking, AI citation presence, or commercial conversion revenue outcomes are guaranteed</strong>.
-    </div>
+    ${modeNotice}
 
     <div class="meta-grid">
-      <div class="card"><div>Total Contract Fee</div><div class="card-val">$${sow.commercial_total_fee_usd.toLocaleString()}</div></div>
+      <div class="card"><div>Total Contract Fee</div><div class="card-val">$${sow.commercial_total_fee_usd.toLocaleString('en-US', { minimumFractionDigits: (sow.commercial_total_fee_minor % 100 === 0) ? 0 : 2, maximumFractionDigits: 2 })}</div></div>
       <div class="card"><div>Admitted SOW Requirements</div><div class="card-val">${sow.admissibility_gate.admitted_count}</div></div>
       <div class="card"><div>Refused / Excluded Scope</div><div class="card-val" style="color:var(--danger);">${sow.admissibility_gate.refused_count}</div></div>
       <div class="card"><div>Contracted Work Packages</div><div class="card-val">${sow.work_packages.length}</div></div>
@@ -636,10 +1013,10 @@ export function renderSowHtml(sow) {
 
     <h2 class="section-title">1. Executive Scope Statement</h2>
     <div class="card">
-      <p><strong>Objective:</strong> ${sow.executive_scope.business_objective}</p>
-      <p><strong>In-Scope Properties:</strong> <code>${sow.executive_scope.in_scope_properties.join(', ')}</code></p>
-      <p><strong>In-Scope Systems:</strong> ${sow.executive_scope.in_scope_systems.join('; ')}</p>
-      <p><strong>Boundaries:</strong> ${sow.executive_scope.organizational_boundaries}</p>
+      <p><strong>Objective:</strong> ${escapeHtml(sow.executive_scope.business_objective)}</p>
+      <p><strong>In-Scope Properties:</strong> <code>${escapeHtml(sow.executive_scope.in_scope_properties.join(', '))}</code></p>
+      <p><strong>In-Scope Systems:</strong> ${escapeHtml(sow.executive_scope.in_scope_systems.join('; '))}</p>
+      <p><strong>Boundaries:</strong> ${escapeHtml(sow.executive_scope.organizational_boundaries)}</p>
     </div>
 
     <h2 class="section-title">2. Scope Admissibility Gate & Excluded Findings Log</h2>
@@ -650,11 +1027,11 @@ export function renderSowHtml(sow) {
       <tbody>
         ${sow.admissibility_gate.refusal_log.map((r) => `
           <tr>
-            <td><span class="code-ref">${r.finding_id}</span></td>
-            <td>${r.subject}</td>
-            <td><code>${r.gate_failed}</code></td>
-            <td><span class="badge badge-refuse">${r.refusal_code}</span></td>
-            <td>${r.refusal_rationale}</td>
+            <td><span class="code-ref">${escapeHtml(r.finding_id)}</span></td>
+            <td>${escapeHtml(r.subject)}</td>
+            <td><code>${escapeHtml(r.gate_failed)}</code></td>
+            <td><span class="badge badge-refuse">${escapeHtml(r.refusal_code)}</span></td>
+            <td>${escapeHtml(r.refusal_rationale)}</td>
           </tr>
         `).join('')}
       </tbody>
@@ -668,11 +1045,11 @@ export function renderSowHtml(sow) {
       <tbody>
         ${sow.delivery_schedule.milestones.map((m) => `
           <tr>
-            <td><strong>${m.milestone_id}</strong></td>
-            <td>${m.name}</td>
-            <td><span class="code-ref">${m.work_package_id}</span></td>
-            <td>${m.billing_trigger}</td>
-            <td style="font-weight:bold; color:var(--success);">$${m.fee_usd.toLocaleString()} USD</td>
+            <td><strong>${escapeHtml(m.milestone_id)}</strong></td>
+            <td>${escapeHtml(m.name)}</td>
+            <td><span class="code-ref">${escapeHtml(m.work_package_id)}</span></td>
+            <td>${escapeHtml(m.billing_trigger)}</td>
+            <td style="font-weight:bold; color:var(--success);">$${m.fee_usd.toLocaleString('en-US', { minimumFractionDigits: (m.fee_minor % 100 === 0) ? 0 : 2, maximumFractionDigits: 2 })} USD</td>
           </tr>
         `).join('')}
       </tbody>
@@ -687,13 +1064,13 @@ export function renderSowHtml(sow) {
       <tbody>
         ${sow.traceability_matrix.map((t) => `
           <tr>
-            <td><span class="code-ref">${t.finding_id}</span></td>
-            <td>${t.recommendation}</td>
-            <td><strong>${t.sow_requirement_id}</strong></td>
-            <td>${t.deliverable_id}</td>
-            <td><code>${t.acceptance_test_id}</code></td>
-            <td>${t.owner}</td>
-            <td><span class="code-ref">${t.evidence_id}</span></td>
+            <td><span class="code-ref">${escapeHtml(t.finding_id)}</span></td>
+            <td>${escapeHtml(t.recommendation)}</td>
+            <td><strong>${escapeHtml(t.sow_requirement_id)}</strong></td>
+            <td>${escapeHtml(t.deliverable_id)}</td>
+            <td><code>${escapeHtml(t.acceptance_test_id)}</code></td>
+            <td>${escapeHtml(t.owner)}</td>
+            <td><span class="code-ref">${escapeHtml(t.evidence_ids?.join(', ') || t.evidence_id)}</span></td>
           </tr>
         `).join('')}
       </tbody>
@@ -702,7 +1079,7 @@ export function renderSowHtml(sow) {
     <h2 class="section-title">Signatures & Contractual Authorization</h2>
     <table class="sig-table">
       <thead>
-        <tr><th>For Customer: ${sow.client.name}</th><th>For Supplier: ${sow.supplier.name}</th></tr>
+        <tr><th>For Customer: ${escapeHtml(sow.client.name)}</th><th>For Supplier: ${escapeHtml(sow.supplier.name)}</th></tr>
       </thead>
       <tbody>
         <tr>
@@ -727,10 +1104,15 @@ export function renderSowHtml(sow) {
 }
 
 /**
- * Export SOW deliverable to filesystem or string
+ * Export SOW deliverable to filesystem or string with strict schema validation
  */
 export async function exportSow(root, options = {}) {
   const sow = await generateSow(root, options);
+  const validation = validateAgainst('sow.schema.json', sow);
+  if (!validation.valid) {
+    throw new SowError(`Generated SOW violates schemas/sow.schema.json: ${validation.errors.join('; ')}`, 'SCHEMA_VALIDATION_FAILED');
+  }
+
   const format = options.format || 'markdown';
   let content = '';