@elitedcs/ghl-mcp 3.70.0 → 3.72.0

package/skills/blueprint/examples/validate-plan.cjs

@@ -1,21 +1,58 @@
 #!/usr/bin/env node
-// Validates an Intake-to-Build §5 build plan against the contract rules.
-// Not the MCP's authoritative Zod validator (that lives in the mcp repo) — this is
-// atlas's self-check that the skill's output is internally consistent + schema-shaped:
-// every ref resolves, no dangling pointers, GHL-correct enums, workflow sanity.
-// Usage: node validate-plan.cjs [plan.json]
+// Validates an Intake-to-Build §5 build plan — or a preset skeleton — against the contract rules.
+// Not the MCP's authoritative Zod validator (src/intake-to-build/plan.ts) — this is the skill's
+// self-check that its output is internally consistent + schema-shaped: every ref resolves, no
+// dangling pointers, GHL-correct enums, workflow sanity, and the Tier 1 v2 rules (a nurture spans
+// >= 30 days, a speed-to-lead ENDS with a hand-off, every person-step carries a userRef, every
+// message lives once as a template with full copy).
+//
+// Usage: node validate-plan.cjs [plan.json | preset.json]
+//   A file with a top-level `skeleton` is a PRESET: it is validated as the maximal plan (every
+//   conditionalOn taken as true, every fillFrom resolved to its default, the role placeholder
+//   user.owner accepted). Everything else is validated as a plan.
 
 const fs = require('fs');
 const path = require('path');
 
-const planPath = process.argv[2] || path.join(__dirname, 'sample-build-plan.json');
-const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+const filePath = process.argv[2] || path.join(__dirname, 'sample-build-plan.json');
+const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+const isPreset = raw && typeof raw === 'object' && raw.skeleton && typeof raw.skeleton === 'object';
 
 const errors = [];
 const warns = [];
 const E = (m) => errors.push(m);
 const W = (m) => warns.push(m);
 
+// ---- preset → maximal plan ----
+function resolvePreset(preset) {
+  const sk = JSON.parse(JSON.stringify(preset.skeleton));
+  const resolveFill = (v) => (v && !Array.isArray(v) && typeof v === 'object' && v.fillFrom) ? (v.default || []) : v;
+  if (sk.users) sk.users = resolveFill(sk.users);
+  (sk.pipelines || []).forEach((p) => {
+    p.stages = resolveFill(p.stages).map((s, i) => ({ ...s, position: s.position == null ? i : s.position }));
+  });
+  const strip = (v) => {
+    if (Array.isArray(v)) return v.map(strip);
+    if (v && typeof v === 'object') {
+      const o = {};
+      for (const [k, val] of Object.entries(v)) { if (k === 'conditionalOn' || k.startsWith('_')) continue; o[k] = strip(val); }
+      return o;
+    }
+    return v;
+  };
+  const plan = strip(sk);
+  plan.schemaVersion = preset.schemaVersion;
+  plan.planId = `preset:${preset.presetId}`;
+  plan.briefId = 'preset';
+  plan.preset = preset.presetId;
+  plan.summary = preset.description;
+  plan.idMap = {};
+  if (!preset.presetVersion) E('preset: missing presetVersion');
+  if (!preset.selectors) E('preset: missing selectors');
+  return plan;
+}
+const plan = isPreset ? resolvePreset(raw) : raw;
+
 const DATA_TYPES = new Set(['TEXT', 'LARGE_TEXT', 'NUMERICAL', 'PHONE', 'MONETORY', 'CHECKBOX', 'SINGLE_OPTIONS', 'MULTIPLE_OPTIONS', 'FLOAT', 'DATE', 'TEXTBOX_LIST', 'FILE_UPLOAD', 'SIGNATURE']);
 const CAL_TYPES = new Set(['round_robin', 'event', 'class_booking', 'collective', 'service_booking']);
 const OWNERS = new Set(['OPERATOR-UI', 'OPERATOR-EXT', 'TEAM', 'JERRY-UI', 'JERRY-EXT']); // canonical (v3.44+) + legacy accepted
@@ -25,6 +62,8 @@ const MODELS = new Set(['contact', 'opportunity']);
 const refs = new Set();
 const addRef = (r) => { if (refs.has(r)) E(`duplicate ref: ${r}`); refs.add(r); };
 
+(plan.users || []).forEach(u => addRef(u.ref)); // v2
+if (isPreset) refs.add('user.owner'); // role placeholder, resolved per step at fill time
 (plan.pipelines || []).forEach(p => { addRef(p.ref); (p.stages || []).forEach(s => addRef(s.ref)); });
 (plan.customFields || []).forEach(f => addRef(f.ref));
 (plan.tags || []).forEach(t => addRef(t.ref));
@@ -34,10 +73,15 @@ const addRef = (r) => { if (refs.has(r)) E(`duplicate ref: ${r}`); refs.add(r);
 (plan.funnels || []).forEach(f => { addRef(f.ref); (f.pages || []).forEach(pg => addRef(pg.ref)); });
 (plan.emails || []).forEach(e => addRef(e.ref));
 (plan.sms || []).forEach(s => addRef(s.ref));
+((plan.templates || {}).emails || []).forEach(t => addRef(t.ref)); // v2
+((plan.templates || {}).sms || []).forEach(t => addRef(t.ref));    // v2
 (plan.workflows || []).forEach(w => addRef(w.ref));
 (plan.handoffs || []).forEach(h => addRef(h.ref));
 
 const need = (r, where) => { if (r == null) return; if (!refs.has(r)) E(`dangling ref ${r} (in ${where})`); };
+// v2: a userRef may be the pending sentinel ("no staff yet — build it, report it as waiting").
+const USER_PENDING = 'user.__pending__';
+const needUser = (r, where) => { if (r == null) return; if (r === USER_PENDING) { W(`${where}: ${USER_PENDING} — built, reported as waiting for a staff member`); return; } need(r, where); };
 
 // ---- top level ----
 if (plan.schemaVersion !== '0.1') W(`schemaVersion is ${plan.schemaVersion}, expected 0.1`);
@@ -48,11 +92,24 @@ if (plan.idMap == null || Object.keys(plan.idMap).length) W('idMap should be pre
 (plan.customFields || []).forEach(f => {
   if (!DATA_TYPES.has(f.dataType)) E(`customField ${f.ref}: bad dataType "${f.dataType}"`);
   if (f.model && !MODELS.has(f.model)) E(`customField ${f.ref}: bad model "${f.model}"`);
+  if (['SINGLE_OPTIONS', 'MULTIPLE_OPTIONS', 'CHECKBOX'].includes(f.dataType) && !(f.options && f.options.length)) W(`customField ${f.ref}: ${f.dataType} with no options`);
+});
+
+// ---- users (v2) ----
+const emailsSeen = new Set();
+(plan.users || []).forEach(u => {
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(u.email || '')) E(`user ${u.ref}: email "${u.email}" is not an address`);
+  if (!['admin', 'user'].includes(u.role)) E(`user ${u.ref}: bad role "${u.role}"`);
+  if (!u.firstName || !u.lastName) E(`user ${u.ref}: firstName and lastName are required`);
+  const k = String(u.email || '').toLowerCase(); if (emailsSeen.has(k)) E(`user ${u.ref}: duplicate email ${u.email}`); emailsSeen.add(k);
 });
 
 // ---- calendars ----
 (plan.calendars || []).forEach(c => {
   if (!CAL_TYPES.has(c.calendarType)) E(`calendar ${c.ref}: bad calendarType "${c.calendarType}"`);
+  (c.teamMemberRefs || []).forEach(r => need(r, `calendar ${c.ref}.teamMemberRefs`)); // v2
+  const needsStaff = c.requiresStaff === true || c.calendarType === 'round_robin' || c.calendarType === 'collective';
+  if ((plan.users || []).length && needsStaff && !(c.teamMemberRefs && c.teamMemberRefs.length)) W(`calendar ${c.ref}: needs staff but lists no teamMemberRefs`);
 });
 
 // ---- custom values ----
@@ -72,30 +129,136 @@ if (plan.idMap == null || Object.keys(plan.idMap).length) W('idMap should be pre
   (f.pages || []).forEach(pg => { need(pg.formRef, `page ${pg.ref}.formRef`); need(pg.calendarRef, `page ${pg.ref}.calendarRef`); });
 });
 
+// ---- templates (v2): every message lives once, with FULL copy ----
+const tplEmails = (plan.templates || {}).emails || [];
+const tplSms = (plan.templates || {}).sms || [];
+const smsEstimate = (body) => body
+  .replace(/\{\{contact\.first_name\}\}/g, 'Jennifer').replace(/\{\{custom_values\.business_name\}\}/g, 'Glow Aesthetics Med Spa')
+  .replace(/\{\{custom_values\.owner_first_name\}\}/g, 'Dana').replace(/\{\{custom_values\.booking_link\}\}/g, 'https://link.example/abcdefghijk')
+  .replace(/\{\{custom_values\.store_link\}\}/g, 'https://shop.example/abc').replace(/\{\{custom_values\.business_phone\}\}/g, '(555) 555-0100')
+  .replace(/\{\{appointment\.start_time\}\}/g, 'Tue Sep 2, 10:30 AM').replace(/\{\{[^}]+\|\|\s*([^}]+)\}\}/g, '$1').replace(/\{\{[^}]+\}\}/g, 'XXXXXXXX');
+tplEmails.forEach(t => {
+  if (!t.ref.startsWith('email_template.')) E(`template ${t.ref}: email templates use the email_template.* namespace`);
+  if (!t.name) E(`template ${t.ref}: missing name`);
+  if (!t.subject || !t.subject.trim()) E(`template ${t.ref}: missing subject`);
+  else if (t.subject.replace(/\{\{[^}]+\}\}/g, 'Jennifer').length > 60) W(`template ${t.ref}: subject over 60 chars (copy-guide: 45 or fewer)`);
+  if (!t.html || !t.html.trim()) E(`template ${t.ref}: html is empty (a template is FULL copy, never an outline)`);
+  else if (!/^\s*<[a-z]/i.test(t.html)) E(`template ${t.ref}: html must be HTML (starts with a tag)`);
+  if (t.html && !/\{\{contact\.first_name\}\}/.test(t.html)) W(`template ${t.ref}: no {{contact.first_name}} — copy-guide asks every message to address one person`);
+});
+tplSms.forEach(t => {
+  if (!t.ref.startsWith('sms_template.')) E(`template ${t.ref}: SMS templates use the sms_template.* namespace`);
+  if (!t.name) E(`template ${t.ref}: missing name`);
+  if (!t.body || !t.body.trim()) E(`template ${t.ref}: body is empty (a template is FULL copy, never an outline)`);
+  else {
+    const n = smsEstimate(t.body).length;
+    if (n > 320) E(`template ${t.ref}: ~${n} chars rendered — SMS hard cap is 320 (two segments)`);
+    else if (n > 250) W(`template ${t.ref}: ~${n} chars rendered — over the 160-char single segment; keep under 250 where you can`);
+  }
+});
+const nameDup = (list, label) => { const seen = new Map(); list.forEach(o => { const k = String(o.name || '').trim().toLowerCase(); if (seen.has(k)) E(`${label} "${o.ref}" and "${seen.get(k)}" share the name "${o.name}"`); seen.set(k, o.ref); }); };
+nameDup(tplEmails, 'templates.emails'); nameDup(tplSms, 'templates.sms'); nameDup(plan.workflows || [], 'workflows');
+
+// ---- email / sms assets: templateRef resolves to the right kind; a sent asset has a body or a template ----
+(plan.emails || []).forEach(e => {
+  if (e.templateRef) { need(e.templateRef, `email ${e.ref}.templateRef`); if (!e.templateRef.startsWith('email_template.')) E(`email ${e.ref}: templateRef must be an email_template.*`); }
+  if (!isPreset && !e.body && !e.templateRef) W(`email ${e.ref}: outline only (no body, no templateRef) — will report needsContent if a workflow sends it`);
+});
+(plan.sms || []).forEach(s => {
+  if (s.templateRef) { need(s.templateRef, `sms ${s.ref}.templateRef`); if (!s.templateRef.startsWith('sms_template.')) E(`sms ${s.ref}: templateRef must be an sms_template.*`); }
+  if (!isPreset && !s.body && !s.templateRef) W(`sms ${s.ref}: outline only (no body, no templateRef) — will report needsContent if a workflow sends it`);
+});
+
 // ---- workflows ----
 const stageRefs = new Set();
 (plan.pipelines || []).forEach(p => (p.stages || []).forEach(s => stageRefs.add(s.ref)));
+const days = (acts) => (acts || []).reduce((d, a) => a.type === 'wait' ? d + a.value * ({ minutes: 1 / 1440, hours: 1 / 24, days: 1 }[a.unit] || 0) : d, 0);
+const spanDays = (w) => { let d = days(w.actions); (w.actions || []).forEach(a => { if (a.type === 'find_opportunity') d += Math.max(days(a.found), days(a.notFound)); }); return d; };
+const nodeCount = (w) => (w.actions || []).reduce((n, a) => n + (a.type === 'find_opportunity' ? 3 + (a.found || []).length + (a.notFound || []).length : 1), 0);
+const nurtureTags = new Set((plan.workflows || []).filter(x => /nurture/i.test(x.name || '') && x.trigger && x.trigger.tagRef).map(x => x.trigger.tagRef));
 (plan.workflows || []).forEach(w => {
   if (!w.trigger || !w.trigger.type) E(`workflow ${w.ref}: missing trigger`);
-  if (w.trigger) { need(w.trigger.formRef, `wf ${w.ref} trigger.formRef`); need(w.trigger.tagRef, `wf ${w.ref} trigger.tagRef`); need(w.trigger.calendarRef, `wf ${w.ref} trigger.calendarRef`); }
+  if (w.trigger) {
+    need(w.trigger.formRef, `wf ${w.ref} trigger.formRef`); need(w.trigger.tagRef, `wf ${w.ref} trigger.tagRef`); need(w.trigger.calendarRef, `wf ${w.ref} trigger.calendarRef`);
+    need(w.trigger.pipelineRef, `wf ${w.ref} trigger.pipelineRef`); need(w.trigger.hasTagRef, `wf ${w.ref} trigger.hasTagRef`);
+    if (w.trigger.stageRef && !stageRefs.has(w.trigger.stageRef)) E(`wf ${w.ref} trigger.stageRef ${w.trigger.stageRef} not a defined stage`);
+    if (w.trigger.type === 'call_status' && !(w.trigger.callStatuses && w.trigger.callStatuses.length)) E(`workflow ${w.ref}: a call_status trigger needs callStatuses (else it fires on EVERY call)`);
+    if (['tag_added', 'appointment_status', 'appointment_booked'].includes(w.trigger.type)) E(`workflow ${w.ref}: trigger type "${w.trigger.type}" is not native — use contact_tag / appointment`);
+  }
   if (!Array.isArray(w.actions) || w.actions.length === 0) E(`workflow ${w.ref}: no actions`);
   if ((w.actions || []).length > 40) E(`workflow ${w.ref}: >40 actions (split required)`);
-  (w.actions || []).forEach((a, i) => {
-    const at = `wf ${w.ref} action[${i}] ${a.type}`;
-    need(a.tagRef, `${at}.tagRef`); need(a.emailRef, `${at}.emailRef`); need(a.smsRef, `${at}.smsRef`);
+  if (nodeCount(w) > 40) E(`workflow ${w.ref}: expands to ${nodeCount(w)} nodes (> 40)`);
+  const checkAction = (a, at) => {
+    need(a.tagRef, `${at}.tagRef`); need(a.emailRef, `${at}.emailRef`); need(a.smsRef, `${at}.smsRef`); need(a.fieldRef, `${at}.fieldRef`);
     need(a.pipelineRef, `${at}.pipelineRef`); need(a.workflowRef, `${at}.workflowRef`);
+    need(a.templateRef, `${at}.templateRef`); needUser(a.userRef, `${at}.userRef`); // v2
+    if (a.type === 'send_email' && !a.emailRef && !a.templateRef) E(`${at}: needs emailRef or templateRef`);
+    if (a.type === 'send_sms' && !a.smsRef && !a.templateRef) E(`${at}: needs smsRef or templateRef`);
+    if (a.type === 'internal_notification' && !a.userRef && !a.to) E(`E_NO_USER_REF: ${at}: needs userRef (or user.__pending__)`);
+    if (a.type === 'internal_notification' && !a.userRef && a.to) W(`${at}: literal "to" instead of a userRef`);
+    if (a.type === 'task_notification' && !a.userRef) W(`${at}: task has no userRef — nobody owns it`);
+    if (a.type === 'assign_user' && !a.userRef) E(`${at}: needs userRef`);
     if (a.stageRef && !stageRefs.has(a.stageRef)) E(`${at}: stageRef ${a.stageRef} not a defined stage`);
+    if (a.type === 'wait' && !(a.value > 0 && ['minutes', 'hours', 'days'].includes(a.unit))) E(`${at}: wait needs value > 0 and unit minutes|hours|days`);
+    if (a.type === 'wait_appointment' && (!w.trigger || w.trigger.type !== 'appointment')) W(`${at}: wait_appointment outside an appointment-triggered workflow`);
+  };
+  let seenFind = false;
+  (w.actions || []).forEach((a, i) => {
+    const at = `wf ${w.ref} action[${i}] ${a.type}`;
+    checkAction(a, at);
+    if (a.type === 'find_opportunity') {
+      seenFind = true;
+      if (i !== w.actions.length - 1) E(`${at}: find_opportunity must be the LAST action`);
+      (a.found || []).forEach((c, ci) => checkAction(c, `${at}.found[${ci}] ${c.type}`));
+      (a.notFound || []).forEach((c, ci) => checkAction(c, `${at}.notFound[${ci}] ${c.type}`));
+    } else if (a.type === 'update_opportunity' && !seenFind) {
+      W(`${at}: update_opportunity with no find_opportunity before it silently does nothing`);
+    }
   });
+  // v2 rules (mirror validateBuildPlan): a nurture spans >= 30 days; a speed-to-lead ENDS with a hand-off.
+  if (/nurture/i.test(w.name || '')) {
+    const d = spanDays(w);
+    if (d < 30) E(`E_NURTURE_TOO_SHORT: workflow ${w.ref} spans ${d} days of waits (needs >= 30)`);
+  }
+  if (/win.?back/i.test(w.name || '')) {
+    const d = spanDays(w);
+    if (d < 30) E(`E_WINBACK_TOO_SHORT: workflow ${w.ref} spans ${d} days of waits (owner rule: win-back is 30+ days)`);
+  }
+  if (/speed/i.test(w.name || '')) {
+    const handoff = (a) => !!a && (a.type === 'add_to_workflow' || (a.type === 'add_contact_tag' && nurtureTags.has(a.tagRef)));
+    const last = (w.actions || [])[(w.actions || []).length - 1];
+    const ok = last && last.type === 'find_opportunity'
+      ? [last.found, last.notFound].every(arm => arm && arm.length && handoff(arm[arm.length - 1]))
+      : handoff(last);
+    if (!ok) E(`E_NO_HANDOFF: workflow ${w.ref} must END with add_to_workflow or add_contact_tag of a nurture trigger tag`);
+    const kinds = new Set((w.actions || []).map(a => a.type));
+    for (const k of ['send_sms', 'send_email', 'task_notification', 'internal_notification', 'create_opportunity']) {
+      if (!kinds.has(k)) W(`workflow ${w.ref}: a v2 speed-to-lead should include ${k}`);
+    }
+    if ((w.actions || []).filter(a => a.type === 'send_sms' || a.type === 'send_email').length < 3) W(`workflow ${w.ref}: fewer than 3 touches — the owner rule is instant + 2nd + 3rd touch`);
+    if ((w.actions || []).length < 10) W(`workflow ${w.ref}: under 10 actions — v2 speed-to-lead is 10+`);
+    if ((w.actions || []).some(a => a.type === 'add_to_workflow')) W(`workflow ${w.ref}: add_to_workflow has no live-proven native shape; prefer the tag hand-off`);
+  }
+  if (/replied|reply/i.test(w.name || '')) {
+    const kinds = new Set((w.actions || []).map(a => a.type));
+    for (const k of ['remove_from_workflow', 'add_contact_tag', 'internal_notification']) if (!kinds.has(k)) W(`workflow ${w.ref}: an exit workflow should include ${k}`);
+  }
   // nurture exit hygiene: any wf with send_* + waits should stop on response OR be a one-shot route
   const hasSends = (w.actions || []).some(a => a.type === 'send_email' || a.type === 'send_sms');
   const hasWaits = (w.actions || []).some(a => a.type === 'wait');
   if (hasSends && hasWaits && w.stopOnResponse !== true) W(`workflow ${w.ref}: multi-step send sequence not stopOnResponse`);
 });
+// every nurture trigger tag must be added somewhere (the hand-off actually happens)
+for (const t of nurtureTags) {
+  const added = (plan.workflows || []).some(w => JSON.stringify(w.actions).includes(`"add_contact_tag","tagRef":"${t}"`));
+  if (!added) W(`nurture trigger tag ${t} is never added by any workflow — nothing hands leads into the nurture`);
+}
 
 // ---- handoffs ----
 (plan.handoffs || []).forEach(h => {
   if (!OWNERS.has(h.owner)) E(`handoff ${h.ref}: bad owner "${h.owner}"`);
   if (!h.successCheck) E(`handoff ${h.ref}: missing successCheck`);
+  if (!h.instruction) E(`handoff ${h.ref}: missing instruction`);
   (h.blocks || []).forEach(b => {
     // blocks may use a wildcard like sms.* — accept wildcard if any ref in that namespace exists
     if (b.endsWith('.*')) { const ns = b.slice(0, -2); if (![...refs].some(r => r.startsWith(ns + '.'))) W(`handoff ${h.ref}: blocks "${b}" matches nothing`); }
@@ -103,9 +266,24 @@ const stageRefs = new Set();
   });
   if (h.produces) need(h.produces, `handoff ${h.ref}.produces`);
 });
+// A2P gating is workflow-level: every SMS-bearing workflow must be listed by handoff.a2p when it exists
+const a2p = (plan.handoffs || []).find(h => h.ref === 'handoff.a2p');
+if (a2p) {
+  (plan.workflows || []).forEach(w => {
+    if (JSON.stringify(w.actions).includes('"send_sms"') && !(a2p.blocks || []).includes(w.ref)) E(`handoff.a2p.blocks does not list SMS-bearing workflow ${w.ref} (it would publish before A2P)`);
+  });
+}
+
+// ---- merge-field hygiene: custom values referenced by copy must exist ----
+const cvNames = new Set((plan.customValues || []).map(c => c.name));
+const allCopy = [...tplEmails.map(t => t.subject + ' ' + t.html), ...tplSms.map(t => t.body)].join('\n');
+for (const m of allCopy.matchAll(/\{\{custom_values\.([a-z0-9_]+)\}\}/g)) {
+  if (!cvNames.has(m[1])) E(`copy references {{custom_values.${m[1]}}} but no custom value named "${m[1]}" is in the plan`);
+}
 
 // ---- report ----
 const counts = {
+  users: (plan.users || []).length,
   pipelines: (plan.pipelines || []).length,
   stages: stageRefs.size,
   customFields: (plan.customFields || []).length,
@@ -116,12 +294,16 @@ const counts = {
   funnels: (plan.funnels || []).length,
   emails: (plan.emails || []).length,
   sms: (plan.sms || []).length,
+  templates: tplEmails.length + tplSms.length,
   workflows: (plan.workflows || []).length,
+  actions: (plan.workflows || []).reduce((n, w) => n + (w.actions || []).length, 0),
+  touches: (plan.workflows || []).reduce((n, w) => n + (w.actions || []).filter(a => a.type === 'send_email' || a.type === 'send_sms').length, 0),
   handoffs: (plan.handoffs || []).length,
 };
 
-console.log(`Plan: ${path.basename(planPath)}  (preset ${plan.preset}, ${refs.size} refs)`);
+console.log(`${isPreset ? 'Preset' : 'Plan'}: ${path.basename(filePath)}  (${isPreset ? `${raw.presetId} v${raw.presetVersion}` : `preset ${plan.preset}`}, ${refs.size} refs)`);
 console.log('Counts:', JSON.stringify(counts));
+(plan.workflows || []).forEach(w => console.log(`  ${w.name}: ${(w.actions || []).length} actions, ${Math.round(spanDays(w) * 100) / 100} days of waits${w.stopOnResponse ? ', stops on reply' : ''}`));
 if (warns.length) { console.log(`\nWARN (${warns.length}):`); warns.forEach(w => console.log('  - ' + w)); }
 if (errors.length) { console.log(`\nERRORS (${errors.length}):`); errors.forEach(e => console.log('  ✗ ' + e)); process.exit(1); }
-console.log('\n✓ VALID — every ref resolves, enums correct, workflows sane. Schema-valid §5 plan.');
+console.log(`\n✓ VALID — every ref resolves, enums correct, workflows sane, v2 rules met. Schema-valid §5 ${isPreset ? 'preset skeleton' : 'plan'}.`);

package/skills/blueprint/presets/clinic-launch-a2p.preset.json

@@ -102,6 +102,7 @@
         "ref": "calendar.event",
         "name": "{{business.name}} Launch Event || Launch Event",
         "calendarType": "event",
+        "_slotDuration": "Carry the appointment length from the brief (brief.calendars[].durationMinutes, or the words in the calendar answer: \"15 minutes\" \u2192 15) onto slotDuration (minutes, slotDurationUnit \"mins\"). This preset value applies ONLY when the brief gives no length; without any slotDuration GoHighLevel builds 30-minute slots (finding 25).",
         "openHours": [{ "daysOfTheWeek": [1, 2, 3, 4, 5], "hours": [{ "openHour": 9, "openMinute": 0, "closeHour": 18, "closeMinute": 0 }] }],
         "availabilityType": 0,
         "slotDuration": 30,

package/skills/blueprint/presets/clinic.md

@@ -0,0 +1,60 @@
+# Preset: Clinic / Practice
+
+**File:** `clinic.preset.json` · **id:** `clinic` · **version:** 2.0.0 · **default:** no
+**Source:** Generalized from the proven clinic builds (Lux Bio Therapy, QA Test Clinic patterns) with the intake industry pack "clinic" (insurance_or_cash, new_patient_offer, compliance_notes); v2 depth per the owner review of 2026-08-26.
+
+## When it is selected
+Routes from the "Clinic / practice" business type and the `clinic` / `practice` / `chiro` / `dental` / `pt` / `functional_medicine` aliases. Med spas route to `med_spa`; a time-boxed launch event routes to `clinic_launch_a2p`.
+
+## What it builds (skeleton, v2 depth)
+- **Users** — one per `brief.team.staff[]` entry. Every alert, task and assignment step points at a `userRef`; in the skeleton that is the role placeholder `user.owner`, resolved at fill time from `team.notifyName` (alerts) and `team.callsName` (tasks, assignment). No staff yet → the steps stay, pointed at `user.__pending__`, and the build reports them as waiting.
+- **1 pipeline** — "Patient Pipeline": New Patient Lead → Contacted → Visit Booked* → Showed* → Care Plan Accepted → Active Patient → Lost. Overridden by `goal.salesStages` when the brief supplies them.
+- **6 custom fields** — Lead Source, What Brings You In, Insurance Status, Appointment Date*, New Patient Offer Used*, Estimated Lifetime Value.
+- **24 tags** — source, lifecycle, the hand-off trigger tags (`nurture-start`, `winback-start`, `missed-call`, `no-show`), and interest tags mirrored from the interest field.
+- **4 custom values** — business_name, business_phone, owner_first_name, booking_link. Every message reads business name / phone / signature / links from these, so the copy stays right when details change.
+- **1 calendar** — New Patient Visit (round_robin, Mon-Fri 8-17 default, 45-minute slots, `teamMemberRefs` → the plan users).*
+- **1 intake form + 1 funnel** — "New Patient Request" (first/last/email/phone required + what brings you in + insurance status) and a New Patient Visit opt-in page (the new-patient offer, what the first visit is, A2P consent block) plus a Thank You page with the booking widget.
+- **15 email + 17 SMS templates** — complete, send-ready copy written to `references/copy-guide.md`. The build stage rewrites every one from the real brief (offer, pain points, objections, prices, lead magnet) and keeps the cadence, the single CTA and the merge fields.
+- **8 workflows, 32 customer touches** — see the table.
+
+\* conditional on `goal.bookingNeeded == true`.
+
+## Workflows
+
+| Workflow | Trigger | Actions | Touches | Span of waits | Stops on reply |
+|---|---|---|---|---|---|
+| Speed to Lead | form_submission | 15 | 5 | 1.1 days | yes |
+| Missed Call Text-Back | call_status (missed: no-answer/busy/voicemail) | 7 | 2 | 1 h | yes |
+| Lead Nurture (30 days) | contact_tag (tag.nurture_start) | 28 | 11 | 31 days | yes |
+| Replied - Stop & Route | customer_reply | 9 | 0 | instant | no |
+| Win-back (30 days) | contact_tag (tag.winback_start) | 13 | 5 | 31 days | yes |
+| Visit Booked - Confirm & Move | appointment (confirmed) | 8 | 2 | instant | no |
+| Visit Reminders | appointment (confirmed) | 5 | 3 | instant | no |
+| No-Show Rescue | appointment (noshow) | 14 | 4 | 7 days | yes |
+
+- **Speed to Lead** (15 actions): instant text + email, opportunity card, the contact assigned to whoever takes calls, alert to a real person, a call task due today, a 2nd touch at 20 minutes, a 3rd at 3 hours, a 4th and 5th by the next day, then the hand-off tag `nurture-start` as the last action.
+- **Lead Nurture** (28 actions, 11 touches, 31 days of waits): give, give, ask. Ends with `lifecycle-lapsed` + the `winback-start` hand-off.
+- **Win-back** (13 actions, 5 touches, 31 days of waits): one reason to come back per message, then `lifecycle-lost`.
+- **Replied - Stop & Route**: the exit workflow. Pulls the contact out of every sequence, notes it, marks contacted, alerts a person and creates a 15-minute reply task.
+- **Missed Call Text-Back**: `call_status` trigger scoped to no-answer / busy / voicemail, inbound. Text within seconds, tag, alert, call-back task, one more text an hour later.
+- **New Patient Visit → Confirm & Move, Reminders, No-Show Rescue**: booking stops every sequence and moves (or creates) the opportunity; reminders at 24 h and 2 h; a no-show gets a same-day call task, text and email, two more touches, then hands off to Win-back and moves the card back to Contacted.
+
+### Why sequences hand off with a tag, not add_to_workflow
+Every hand-off is `add_contact_tag` + a `contact_tag` trigger. Both halves are live-proven shapes captured from working GHL workflows (`templates/action-schemas.json`). `add_to_workflow` has no captured native shape there and has not been proven at runtime, so a preset may not use it. Each sequence removes its own trigger tag as its first action so a later hand-off can start it again.
+
+## How the brief shapes it
+| Brief signal | Effect |
+|---|---|
+| `goal.salesStages` present | replaces the default pipeline stages (workflow stage refs are mapped to the nearest equivalent) |
+| `goal.bookingNeeded == false` | drops the calendar, booking stage/tag/fields, the three appointment workflows and the calendar handoffs |
+| `channels.sms == true` | keeps SMS templates, the send_sms actions, Missed Call Text-Back and the A2P gating; otherwise they drop (the email-only nurture still spans 31 days) |
+| staff answers present | fills `users`; every `userRef` resolves to a real person |
+| staff empty | every `userRef` → `user.__pending__`; the steps stay; `handoff.add_staff` holds those workflows DRAFT |
+| `flags` | `needs_a2p` / `stripe_not_connected` / `calendar_oauth_needed` / `email_domain_needed` add the matching handoff |
+| `business.name`, `offer.*`, `audience.*`, `extended.*` | fill object names, custom values and ground every template rewrite |
+
+## Compliance rule for every rewrite
+The templates say "your visit", "what brought you in", "what you came in for". They never say what that is. Keep it that way when the build stage rewrites from the brief, even if the brief names a specialty; the specialty may appear in the business name and the landing page, not in a text or email to a lead. `handoff.compliance_review` puts the final read on the operator.
+
+## Copy notes
+Compliance first: no message names a condition, diagnosis, treatment or medication, and the intake pack's compliance_notes are honored on rewrite. The through-line is "the first visit is mostly listening": what happens minute by minute, how insurance and cash pricing work in plain words, no surprise bills, and why the easy-to-fix stage is the cheap stage. Texts ask one-word questions (new / ongoing / check-up; mornings / afternoons; YES / later).