@domandigital/craft 0.20.2 → 0.20.4

package/dist/index.js

@@ -6555,14 +6555,14 @@ function cv(xs, min) {
 }
 function shapeOf(text) {
   const ss = splitSentences(text);
-  const wordCount = words(text).length;
-  const per100 = (n) => wordCount === 0 ? 0 : 100 * n / wordCount;
+  const wordCount2 = words(text).length;
+  const per100 = (n) => wordCount2 === 0 ? 0 : 100 * n / wordCount2;
   const share2 = (re) => ss.length === 0 ? 0 : ss.filter((s) => re.test(s)).length / ss.length;
   const tri = ss.flatMap(tricolons);
   const commas = (text.match(/,/g) ?? []).length;
   return {
     sentences: ss.length,
-    words: wordCount,
+    words: wordCount2,
     tricolons: tri.length,
     parallelTriads: tri.filter((t) => t.parallel).length,
     stackedConditionals: ss.filter(stackedConditional).length,
@@ -8265,7 +8265,18 @@ var SOURCE_KINDS = [
 var CHOICE_KEYS = ["accent", "ground", "display", "body", "shape", "motif", "signature"];
 var CONSIDERATION = ["low", "considered", "high"];
 var PAGE_TYPES = ["home", "service", "about", "pricing", "booking", "contact", "article", "landing"];
+var PROOF_KINDS = ["work", "people", "credentials", "reviews", "experience", "outcomes"];
+var PROOF_DEPTHS = ["first-look", "on-request"];
+var VIEWPORTS = ["mobile", "tablet", "desktop"];
 var HIERARCHY_FIELDS = ["primaryAction", "order", "lead", "journey"];
+var CONFIDENCE_LENSES = ["relevance", "hierarchy", "evidence", "identity", "action", "disclosure", "personality", "differentiation", "mobile"];
+var REVIEW_BASES = ["observed", "inferred", "preference", "unknown"];
+var INSPECTED_KINDS = ["screenshot", "rendered", "source", "measurement", "content"];
+var REPORTED_KINDS = ["audit", "stakeholder", "customer"];
+var EVIDENCE_KINDS = [...INSPECTED_KINDS, ...REPORTED_KINDS];
+var CHANGE_CLASSES = ["confirmed-correction", "design-hypothesis", "optional-refinement", "no-change"];
+var CHANGE_STEPS = ["copy", "relocate", "group", "imagery", "trust-placement", "adjust-component", "remove-redundancy", "restructure", "new-component"];
+var ADDITIONS = ["carousel", "javascript", "dependency", "animation", "testimonial", "cta", "duplicate-content"];
 
 // src/direction/reason.ts
 var PROPOSED = "PROPOSED:";
@@ -8561,6 +8572,429 @@ function checkOrder(declared, page, snapshot, strict = false) {
   return [{ severity: strict ? "error" : "warn", at: `hierarchy.${page}.order`, message: `the page runs ${rendered.join(", ")}; the file says ${said.join(", ")}` }];
 }
 
+// src/direction/review.ts
+var isObject = (x) => Boolean(x) && typeof x === "object" && !Array.isArray(x);
+var wordCount = (x) => typeof x === "string" ? x.trim().split(/\s+/).filter(Boolean).length : 0;
+var includes = (list, x) => list.includes(x);
+var STEP_RANK = new Map(CHANGE_STEPS.map((s, i) => [s, i]));
+var CLASS_RANK = { "no-change": 0, "optional-refinement": 1, "design-hypothesis": 2, "confirmed-correction": 3 };
+var RENDERED_KINDS = ["screenshot", "rendered", "measurement"];
+var isStructural = (step) => step === "restructure" || step === "new-component";
+var GALLERY = /\b(?:gallery|galleries|carousel|slideshow|slider|swipe(?:able)?|rotating)\b/i;
+function plain2(at, text) {
+  if (wordCount(text) < 8) return [{ severity: "error", at, message: "a sentence at least: say why, in this visitor's terms" }];
+  const t = text;
+  if (PREFERENCE.test(t)) return [{ severity: "error", at, message: "that is a preference, not a reason. Say what it does for this visitor." }];
+  const c = t.match(CONVENTION);
+  if (c) return [{ severity: "error", at, message: `"${c[0]}" is the category's default speaking, not a reason. Say what in this visitor's job it answers.` }];
+  return [];
+}
+function checkProposalShape(at, p, required) {
+  const problems = [];
+  const err = (rest, message) => problems.push({ severity: "error", at: `${at}${rest}`, message });
+  if (!isObject(p)) {
+    if (required) err("", "a proposal is an object: change, step, and optionally adds and touches");
+    return problems;
+  }
+  if (wordCount(p.change) < 3) err(".change", "say what changes, in a few words");
+  if (!includes(CHANGE_STEPS, p.step)) err(".step", `one of ${CHANGE_STEPS.join(", ")}: the smallest step that does it`);
+  if (p.adds !== void 0) {
+    if (!Array.isArray(p.adds) || p.adds.some((a) => !includes(ADDITIONS, a))) err(".adds", `a list drawn from ${ADDITIONS.join(", ")}`);
+  }
+  if (p.comparisons !== void 0) {
+    if (!Array.isArray(p.comparisons)) err(".comparisons", "a list comparing each relevant existing component");
+    else p.comparisons.forEach((c, i) => {
+      if (!isObject(c) || typeof c.existing !== "string" || !c.existing.trim() || typeof c.samePurpose !== "boolean") {
+        err(`.comparisons[${i}]`, "existing, samePurpose and because are required");
+      } else problems.push(...plain2(`${at}.comparisons[${i}].because`, c.because));
+    });
+  }
+  if (p.touches !== void 0 && !includes(SECTION_ROLES, p.touches)) err(".touches", `a section role: ${SECTION_ROLES.join(", ")}`);
+  return problems;
+}
+function checkEvidenceShape(at, e) {
+  const problems = [];
+  const err = (rest, message) => problems.push({ severity: "error", at: `${at}${rest}`, message });
+  if (!isObject(e)) return [{ severity: "error", at, message: "evidence is an object: kind, ref, and a viewport for anything rendered" }];
+  if (!includes(EVIDENCE_KINDS, e.kind)) err(".kind", `one of ${EVIDENCE_KINDS.join(", ")}`);
+  if (typeof e.ref !== "string" || !e.ref.trim()) err(".ref", "where it can be found: a screenshot path, a selector, a quotation, a report");
+  if (e.viewport !== void 0 && !includes(VIEWPORTS, e.viewport)) err(".viewport", `one of ${VIEWPORTS.join(", ")}`);
+  if (includes(RENDERED_KINDS, e.kind) && e.viewport === void 0) err(".viewport", "say which width this was seen at: what is seen at one width is not evidence about another");
+  return problems;
+}
+function checkNoteShape(i, n) {
+  const base = `notes[${i}]`;
+  const problems = [];
+  const err = (rest, message) => problems.push({ severity: "error", at: `${base}${rest}`, message });
+  if (typeof n.id !== "string" || !n.id.trim()) err(".id", "a short name for this note");
+  if (n.page !== void 0 && !includes(PAGE_TYPES, n.page)) err(".page", `one of ${PAGE_TYPES.join(", ")}`);
+  if (!includes(CONFIDENCE_LENSES, n.lens)) err(".lens", `one of ${CONFIDENCE_LENSES.join(", ")}`);
+  if (wordCount(n.observation) < 3) err(".observation", "what was said or seen, as it was said");
+  if (typeof n.raisedBy !== "string" || !n.raisedBy.trim()) err(".raisedBy", "who said it, or what found it");
+  if (!includes(REVIEW_BASES, n.basis)) err(".basis", `one of ${REVIEW_BASES.join(", ")}`);
+  if (!Array.isArray(n.evidence)) err(".evidence", "a list, possibly empty: what supports the note");
+  else n.evidence.forEach((e, j) => problems.push(...checkEvidenceShape(`${base}.evidence[${j}]`, e)));
+  if (n.appliesTo !== void 0 && (!Array.isArray(n.appliesTo) || n.appliesTo.some((v) => !includes(VIEWPORTS, v)))) err(".appliesTo", `a list drawn from ${VIEWPORTS.join(", ")}`);
+  if (n.existing !== void 0 && (!Array.isArray(n.existing) || n.existing.some((x) => typeof x !== "string"))) err(".existing", "a list of what the page already has");
+  if (n.suggested !== void 0) problems.push(...checkProposalShape(`${base}.suggested`, n.suggested, false));
+  const r = n.recommend;
+  if (!isObject(r)) {
+    err(".recommend", "the recommendation: a class, and for anything but no-change a change, a step and a reason");
+    return problems;
+  }
+  if (!includes(CHANGE_CLASSES, r.class)) {
+    err(".recommend.class", `one of ${CHANGE_CLASSES.join(", ")}. no-change is a result, not a failure to answer.`);
+    return problems;
+  }
+  if (r.class === "no-change") {
+    if (r.because !== void 0) problems.push(...plain2(`${base}.recommend.because`, r.because));
+    return problems;
+  }
+  problems.push(...checkProposalShape(`${base}.recommend`, r, true));
+  problems.push(...plain2(`${base}.recommend.because`, r.because));
+  const bigger = isStructural(r.step) || Array.isArray(r.adds) && r.adds.length > 0;
+  if (bigger) {
+    const smaller = Array.isArray(r.smaller) ? r.smaller : [];
+    if (smaller.length === 0) err(".recommend.smaller", "a structural change, or one that adds a carousel, script, dependency, animation, testimonial, call to action or repeated content, says which smaller steps were considered and why none was enough");
+    const limit = STEP_RANK.get(r.step) ?? 0;
+    smaller.forEach((s, j) => {
+      const ok = isObject(s) && includes(CHANGE_STEPS, s.step) && (limit === 0 || (STEP_RANK.get(s.step) ?? 99) < limit);
+      if (!ok) err(`.recommend.smaller[${j}].step`, "a step on the ladder below the one recommended");
+      if (isObject(s)) problems.push(...plain2(`${base}.recommend.smaller[${j}].whyNot`, s.whyNot));
+    });
+  } else {
+    problems.push(...plain2(`${base}.recommend.whyEnough`, r.whyEnough));
+  }
+  if (r.class === "design-hypothesis" && wordCount(r.validation) < 4) err(".recommend.validation", "a hypothesis says how it would be checked: a phone test, five visitors, a read of the enquiries");
+  if (r.requires !== void 0) {
+    if (!Array.isArray(r.requires) || r.requires.some((q) => !isObject(q) || wordCount(q.what) < 2)) err(".recommend.requires", "a list of {what, source?}: facts or assets the change depends on");
+  }
+  return problems;
+}
+function whyNot(p, ctx) {
+  const reasons = [];
+  const adds = Array.isArray(p.adds) ? p.adds : [];
+  if (adds.includes("carousel")) {
+    for (const have of new Set(ctx.existing.filter((e) => GALLERY.test(e)))) {
+      const compared = p.comparisons?.filter((c) => c.existing === have) ?? [];
+      if (compared.length !== 1) reasons.push(`the page already has "${have}". Compare its purpose, content and placement before adding another carousel; duplication is not established by its name.`);
+      else if (compared[0].samePurpose) reasons.push(`the comparison identifies the same purpose as "${have}": ${compared[0].because}. Reuse or adjust that component.`);
+    }
+  }
+  const defensible = (ctx.basis === "observed" || ctx.basis === "inferred") && ctx.impact;
+  if ((isStructural(p.step) || adds.length > 0) && !defensible) {
+    reasons.push("it is a structural change or adds something that costs, and the problem under it is neither observed nor inferred with a stated visitor impact. A preference does not justify it.");
+  }
+  if (p.step === "remove-redundancy" && !(ctx.basis === "observed" && ctx.impact)) {
+    reasons.push("it removes information, and nothing observed shows it is redundant or what it costs the visitor. Useful detail stays unless it is shown not to be.");
+  }
+  if (p.touches && ctx.placed.has(p.touches) && ctx.basis !== "observed") {
+    reasons.push(`the declared order already places "${p.touches}" with a reason. Only something observed overrides a reasoned decision.`);
+  }
+  return reasons;
+}
+function widthsOf(evidence) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const e of evidence) {
+    if (e.viewport) seen.add(e.viewport);
+    else if (e.kind === "content") VIEWPORTS.forEach((v) => seen.add(v));
+  }
+  return VIEWPORTS.filter((v) => seen.has(v));
+}
+function assessReview(input, direction) {
+  const problems = [];
+  const results = [];
+  const fail = (at, message) => problems.push({ severity: "error", at, message });
+  const report2 = () => {
+    const n = (o) => results.filter((r) => r.outcome === o).length;
+    const summary = { change: n("change"), hold: n("hold"), noChange: n("no-change"), gatherEvidence: n("gather-evidence"), verdict: "" };
+    summary.verdict = results.length === 0 ? "The review has no notes to assess." : summary.change + summary.hold + summary.gatherEvidence === 0 ? "The existing design is already appropriate for what was reviewed. No change is recommended." : `${summary.change} change${summary.change === 1 ? "" : "s"} recommended, ${summary.hold} held for something nobody has supplied, ${summary.gatherEvidence} to establish first, ${summary.noChange} needing no change.`;
+    return { valid: !problems.some((p) => p.severity === "error"), problems, results, summary };
+  };
+  if (!isObject(input)) {
+    fail("", "a review is an object: version, subject and notes");
+    return report2();
+  }
+  if (input.context !== void 0 && !["publication", "protected-staging"].includes(input.context)) fail("context", "publication or protected-staging");
+  if (input.version !== 1) fail("version", "version is 1");
+  if (typeof input.subject !== "string" || !input.subject.trim()) fail("subject", "who or what was reviewed");
+  if (!Array.isArray(input.notes)) {
+    fail("notes", "a list of notes");
+    return report2();
+  }
+  const job = direction.job;
+  if (!job) {
+    fail("", "a review is read against the visitor's job, and the art direction has no job map yet. Record it first (craft direction research).");
+    return report2();
+  }
+  const ids = /* @__PURE__ */ new Set();
+  input.notes.forEach((raw, i) => {
+    if (!isObject(raw)) return fail(`notes[${i}]`, "a note is an object");
+    const shape = checkNoteShape(i, raw);
+    if (typeof raw.id === "string") {
+      if (ids.has(raw.id)) shape.push({ severity: "error", at: `notes[${i}].id`, message: `"${raw.id}" is used twice` });
+      ids.add(raw.id);
+    }
+    problems.push(...shape);
+    if (shape.length > 0) return;
+    const note = raw;
+    const page = note.page ?? "home";
+    const adjustments = [];
+    const hierarchy = direction.hierarchy?.[page];
+    const sources = Array.isArray(direction.sources) ? direction.sources : [];
+    const inspected = note.evidence.filter((e) => includes(INSPECTED_KINDS, e.kind));
+    let basis = note.basis;
+    if (basis === "observed" && inspected.length === 0) {
+      basis = note.evidence.length > 0 ? "inferred" : "unknown";
+      adjustments.push(
+        note.evidence.length > 0 ? "declared observed, but everything cited is reported (an audit, a stakeholder, a customer) and nothing was inspected. Read as inferred until someone looks." : "declared observed, but nothing is cited. Read as unknown."
+      );
+    } else if (basis === "inferred" && note.evidence.length === 0) {
+      basis = "unknown";
+      adjustments.push("declared inferred, but nothing supports it. Read as unknown.");
+    }
+    const impactProblems = typeof note.impact === "string" ? checkReason({ at: `notes[${i}].impact`, because: note.impact, sources, tie: "job", job }) : [];
+    const impact = typeof note.impact === "string" && impactProblems.length === 0;
+    const wantsChange = note.recommend.class !== "no-change";
+    if (!impact && (wantsChange || note.suggested)) {
+      adjustments.push(
+        typeof note.impact === "string" ? `no visitor impact tied to this client's job (${impactProblems[0]?.message ?? "none given"}).` : "no visitor impact stated. Something that costs the visitor nothing they can name is a fact or a preference, not an issue, and is not read as one."
+      );
+      if (basis === "inferred") basis = "preference";
+    }
+    const ctx = {
+      note,
+      basis,
+      impact,
+      existing: [...note.existing ?? [], ...(hierarchy?.confidence?.proof ?? []).map((p) => p.what).filter((w) => typeof w === "string")],
+      placed: new Set((hierarchy?.order ?? []).map((o) => o.role))
+    };
+    const examined = widthsOf(note.evidence);
+    const wanted = note.appliesTo ?? (examined.length > 0 ? examined : [...VIEWPORTS]);
+    const claimed = wanted.filter((v) => examined.includes(v));
+    const unknown = VIEWPORTS.filter((v) => wanted.includes(v) && !examined.includes(v));
+    if (unknown.length > 0) adjustments.push(`nothing here was looked at on ${unknown.join(" or ")}, so the note says nothing about it. That stays unknown until it is examined there.`);
+    const rec = note.recommend;
+    const recReasons = wantsChange ? whyNot(rec, ctx) : [];
+    const sugReasons = note.suggested ? whyNot(note.suggested, ctx) : [];
+    const ceiling = basis === "observed" ? impact ? "confirmed-correction" : "optional-refinement" : basis === "inferred" ? "design-hypothesis" : basis === "preference" ? "optional-refinement" : "no-change";
+    let effective = wantsChange ? rec.class : "no-change";
+    if (basis !== "unknown" && CLASS_RANK[effective] > CLASS_RANK[ceiling]) {
+      adjustments.push(`declared ${rec.class}, but a problem that is ${basis}${basis === "observed" && !impact ? " with no stated visitor impact" : ""} supports at most ${ceiling}.`);
+      effective = ceiling;
+    }
+    let withdrawn;
+    if (wantsChange && recReasons.length > 0) {
+      withdrawn = recReasons;
+      effective = "no-change";
+      adjustments.push("the recommended change is withdrawn: " + recReasons.join(" "));
+    }
+    const missing = (rec.requires ?? []).filter((q) => !q.source || !sources.some((s) => s.id === q.source));
+    const outstanding = missing.map((q) => q.what);
+    const blocking = missing.filter((q) => !(input.context === "protected-staging" && q.kind === "asset" && q.phase === "publication" && q.placeholder));
+    if (missing.length > blocking.length) adjustments.push("Protected staging may reserve the explicitly marked placeholder. Required assets remain outstanding for publication; no fact or photograph has been supplied by this review.");
+    let outcome;
+    if (basis === "unknown") {
+      outcome = "gather-evidence";
+      effective = "no-change";
+      if (wantsChange) adjustments.push(`nothing is recommended until the problem is established${rec.validation ? `: ${rec.validation}` : ". Ask the client, or look, first."}`);
+    } else if (effective === "no-change") outcome = "no-change";
+    else if (blocking.length > 0) outcome = "hold";
+    else outcome = "change";
+    if (outcome === "hold") adjustments.push(`held: it depends on ${blocking.map((o) => `"${o.what}"`).join(", ")}, and no source supplies it. Do not write it in. Ask the client.`);
+    let suggested;
+    if (note.suggested) {
+      const recRank = STEP_RANK.get(rec.step ?? "") ?? -1;
+      const sugRank = STEP_RANK.get(note.suggested.step) ?? 0;
+      const sugAdds = (note.suggested.adds ?? []).length;
+      let standing;
+      const reasons = [...sugReasons];
+      if (sugReasons.length > 0) standing = "not-supported";
+      else if (effective === "no-change") {
+        standing = "not-needed";
+        reasons.push("the existing design already answers the problem, or nothing is yet established to answer.");
+      } else if (sugRank > recRank || sugAdds > 0 && (rec.adds ?? []).length === 0) {
+        standing = "comparison-needed";
+        reasons.push("Compare the proposals before selecting one. A smaller implementation is not evidence of a better visitor experience; compare their adequacy against the stated problem and rendered result.");
+      } else standing = "supported";
+      suggested = { standing, reasons };
+    }
+    results.push({
+      id: note.id,
+      page,
+      lens: note.lens,
+      basis: { declared: note.basis, effective: basis },
+      ...suggested ? { suggested } : {},
+      recommend: { declared: rec.class, effective, ...wantsChange ? { step: rec.step } : {}, ...withdrawn ? { withdrawn } : {} },
+      outcome,
+      widths: { examined, claimed, unknown },
+      adjustments,
+      outstanding,
+      publicationReady: outstanding.length === 0
+    });
+  });
+  return report2();
+}
+
+// src/direction/confidence.ts
+function viewportOf(width) {
+  return width < 768 ? "mobile" : width < 1024 ? "tablet" : "desktop";
+}
+var isObject2 = (x) => Boolean(x) && typeof x === "object" && !Array.isArray(x);
+function validateConfidence(page, confidence, job, sources) {
+  const problems = [];
+  const base = `hierarchy.${page}.confidence`;
+  const err = (at, message) => problems.push({ severity: "error", at: `${base}${at}`, message });
+  if (!isObject2(confidence)) {
+    err("", "confidence is an object: `examined` (the widths looked at) and `proof` (what the page offers)");
+    return problems;
+  }
+  if (confidence.examined !== void 0) {
+    if (!Array.isArray(confidence.examined)) err(".examined", `a list of widths: ${VIEWPORTS.join(", ")}`);
+    else for (const v of confidence.examined) if (!VIEWPORTS.includes(v)) err(".examined", `"${String(v)}" is not a width craft knows. Widths are: ${VIEWPORTS.join(", ")}`);
+  }
+  if (confidence.proof !== void 0 && !Array.isArray(confidence.proof)) err(".proof", "a list of evidence items");
+  const proof = Array.isArray(confidence.proof) ? confidence.proof : [];
+  proof.forEach((raw, i) => {
+    const at = `.proof[${i}]`;
+    if (!isObject2(raw)) return err(at, "an evidence item is an object: kind, what, position, depth, because");
+    if (!PROOF_KINDS.includes(raw.kind)) err(`${at}.kind`, `one of ${PROOF_KINDS.join(", ")}`);
+    if (typeof raw.what !== "string" || contentWords(raw.what).size < 2) err(`${at}.what`, 'what it is, in a few words: "photographs of three finished bathrooms", not "proof"');
+    if (typeof raw.position !== "string" || !POSITIONS.has(raw.position)) err(`${at}.position`, 'the section it sits in, or "header" or "sticky"');
+    if (!PROOF_DEPTHS.includes(raw.depth)) err(`${at}.depth`, `${PROOF_DEPTHS.join(" or ")}: met without being sought, or detail a visitor opens`);
+    problems.push(...checkReason({ at: `${base}${at}`, because: raw.because, evidence: raw.evidence, sources, tie: "job", job }));
+  });
+  return problems;
+}
+var IDENTITY_WORRY = /\b(?:strangers?|who(?:'s| is| would| will) (?:coming|doing|treating|seeing|dealing|there)|(?:someone|somebody) (?:i|they|we) (?:have not|haven't|do not|don't) (?:met|know)|have not met|haven't met|not met|in (?:my|their|the) (?:home|house)|into (?:my|their|the) (?:home|house)|accountab\w+)\b/i;
+var LATE_SECTION = 3;
+var identityText = (job) => [job.emotional?.value, job.social?.value, ...Array.isArray(job.objections) ? job.objections : [], ...Array.isArray(job.language) ? job.language : []].filter((x) => typeof x === "string").join(" ");
+var lensOf = (kind) => kind === "people" ? "identity" : "evidence";
+function decisionText(h) {
+  const proof = Array.isArray(h.confidence?.proof) ? h.confidence.proof : [];
+  return [
+    h.primaryAction?.value,
+    h.primaryAction?.because,
+    h.lead?.value,
+    h.lead?.because,
+    ...Array.isArray(h.order) ? h.order.map((o) => o?.because) : [],
+    ...Array.isArray(h.journey) ? h.journey.map((s) => s?.because) : [],
+    ...proof.flatMap((p) => isObject2(p) ? [p.what, p.because] : [])
+  ].filter((x) => typeof x === "string").join(" ");
+}
+function assessConfidence(hierarchy, job, ctx = {}) {
+  const findings = [];
+  if (!isObject2(hierarchy)) return findings;
+  for (const [key, raw] of Object.entries(hierarchy)) {
+    const h = raw;
+    if (!PAGE_TYPES.includes(key) || !isObject2(h) || !isObject2(h.confidence)) continue;
+    const page = key;
+    const at = (rest) => `hierarchy.${page}.confidence${rest}`;
+    const add = (f4) => findings.push({ page, ...f4 });
+    const c = h.confidence;
+    const proof = (Array.isArray(c.proof) ? c.proof : []).filter(isObject2);
+    const order = new Set((Array.isArray(h.order) ? h.order : []).map((o) => o?.role));
+    const bands = new Set((Array.isArray(c.examined) ? c.examined : []).filter((v) => VIEWPORTS.includes(v)));
+    if (ctx.snapshot && (ctx.snapshotPage ?? "home") === page) bands.add(viewportOf(ctx.snapshot.viewport.width));
+    for (const pos of Array.isArray(h.primaryAction?.positions) ? h.primaryAction.positions : []) {
+      if (POSITIONS.has(pos) && pos !== "header" && pos !== "sticky" && !order.has(pos)) {
+        add({
+          lens: "action",
+          basis: "observed",
+          at: `hierarchy.${page}.primaryAction.positions`,
+          message: `the ask "${h.primaryAction.value}" sits in "${pos}", and the declared order has no such section`,
+          why: "A visitor can only take the next step where the page offers it. Either the order or the position is out of date."
+        });
+      }
+    }
+    proof.forEach((p, i) => {
+      const where = at(`.proof[${i}]`);
+      if (POSITIONS.has(p.position) && p.position !== "header" && p.position !== "sticky" && !order.has(p.position)) {
+        add({
+          lens: "hierarchy",
+          basis: "observed",
+          at: `${where}.position`,
+          message: `${p.kind} evidence "${p.what}" sits in "${p.position}", and the declared order has no such section`,
+          why: "Evidence a visitor is meant to meet has to be on the page, in a section the order names."
+        });
+      }
+      const cited = Array.isArray(p.evidence) ? p.evidence : [];
+      if (cited.length === 0) {
+        add({
+          lens: lensOf(p.kind),
+          basis: "unknown",
+          at: `${where}.evidence`,
+          message: `no source in the file shows that "${p.what}" exists`,
+          why: "Confidence built on evidence that is only planned or imagined is the opposite of confidence. Confirm it with the client, and cite what shows it, before the page claims it."
+        });
+      }
+    });
+    const firstLook = new Set(proof.filter((p) => p.depth === "first-look").map((p) => p.kind));
+    proof.forEach((p, i) => {
+      if (p.depth === "on-request" && !firstLook.has(p.kind)) {
+        add({
+          lens: "disclosure",
+          basis: "inferred",
+          at: at(`.proof[${i}].depth`),
+          message: `${p.kind} evidence "${p.what}" is held back for visitors who seek it, and nothing of the same kind is met first`,
+          why: "Detail can wait only if the visitor can tell it is there. Nothing at first look means the evidence may never be found. A line in the header or a short sample in the hero would do; this is a hypothesis, not a rule."
+        });
+      }
+    });
+    if (job && IDENTITY_WORRY.test(identityText(job))) {
+      const sections = Array.isArray(h.order) ? h.order.map((o) => o?.role) : [];
+      const before = (pos) => pos === "header" || pos === "sticky" ? 0 : sections.indexOf(pos);
+      const met = proof.filter((p) => p.kind === "people" && before(p.position) >= 0).map((p) => ({ position: p.position, before: before(p.position) }));
+      const earliest = met.length > 0 ? met.reduce((a, b) => b.before < a.before ? b : a) : void 0;
+      if (earliest && earliest.before >= LATE_SECTION) {
+        add({
+          lens: "identity",
+          basis: "inferred",
+          at: at(".proof"),
+          message: `the job worries about who the visitor would deal with, and the first person is met in "${earliest.position}", after ${earliest.before} other sections`,
+          why: `A visitor who wants to know who is coming may leave or ask before getting there. The smallest change is a name and a line where the ask is first made, not the whole biography moved up: it can stay where it is. This is a hypothesis about the order as declared; check it on the width where it matters.${bands.has("mobile") ? "" : " It has not been examined on a phone."}`
+        });
+      }
+    }
+    if (job && Array.isArray(job.objections)) {
+      const said = contentWords(decisionText(h));
+      job.objections.forEach((o, i) => {
+        if (typeof o !== "string") return;
+        if (shares(contentWords(o), said).length === 0) {
+          add({
+            lens: "relevance",
+            basis: "unknown",
+            at: `job.objections[${i}]`,
+            message: `no decision recorded for this page names the worry "${o}"`,
+            why: "A visitor who arrives with this worry needs something that meets it. Either a decision here does, and its reason should say so, or this page does not have to answer it. This reads wording only: it can miss an answer that uses other words."
+          });
+        }
+      });
+    }
+    if (bands.size === 0) {
+      add({
+        lens: "mobile",
+        basis: "unknown",
+        at: at(".examined"),
+        message: "no width recorded: say which widths these decisions were examined at",
+        why: "The phone is the base layout (STANDARD.md section 10). What was seen at one width says nothing about another until it has been looked at there."
+      });
+    } else {
+      for (const band of VIEWPORTS) {
+        if (bands.has(band)) continue;
+        add({
+          lens: "mobile",
+          basis: "unknown",
+          at: at(".examined"),
+          message: band === "mobile" ? "not examined on a phone" : `not examined at ${band} width; what was seen at ${[...bands].join(" and ")} is not carried to it`,
+          why: band === "mobile" ? "The phone is the base layout every wider one is derived from (STANDARD.md section 10). A page not looked at there has not been looked at where it is designed first." : "Order, prominence and what fits can differ at another width, and nothing recorded shows they do not. Examine it there before treating the finding as true of it."
+        });
+      }
+    }
+  }
+  return findings;
+}
+
 // src/direction/research.ts
 function tradeOf(brief) {
   const text = brief.toLowerCase();
@@ -8591,14 +9025,17 @@ function researchPrompt(input) {
     "4. **Their words.** The phrases they actually use for the problem and for what they want. Quote them exactly.",
     "5. **Who else is involved.** Who do they have to explain or justify the choice to (a partner, a landlord, a tenant, a manager), and what would make them look good or bad to that person?",
     "6. **Consideration.** Do they decide in minutes, days or months? What do they compare before deciding?",
-    "7. **Where they look.** What do they search for, and where do they ask?",
+    "7. **Where they look.** What do they search for, and where do they ask? On a phone or a computer, and at what moment: standing in a kitchen, on a commute, at a desk?",
+    "8. **What would settle it.** Before they would get in touch, what do they check or want to see: work that was actually done, who they would deal with, a registration they can look up, what other customers said, how long the person has done this? Say which of these the people you found actually mention, and do not assume all of them matter.",
+    "9. **The next step.** How do they usually take it: ring, book, send an enquiry, ask for a quotation, look further first? What stops them taking it, and what do they want to know before they do?",
     "",
     "## Do not",
     "",
     `- Do not describe, list, rank or summarise what ${category} websites look like, or how they are laid out.`,
     '- Do not suggest colours, fonts, layouts, sections or visual "inspiration" from this category.',
     "- Do not summarise competitors' marketing. Their claims are the category average; the customer's words are the point.",
-    "- Do not invent quotes. If you cannot find a source for something, say so."
+    "- Do not invent quotes. If you cannot find a source for something, say so.",
+    "- Do not assume the next step is a phone call, or that a business needs a founder's photograph, reviews, credentials or a gallery. Report what these customers say they need, including that they need none of it."
   ];
   if (input.visual) {
     lines.push(
@@ -8929,6 +9366,7 @@ function validateDirection(input, ctx = {}) {
   }
   let job = false;
   let hierarchy = [];
+  let confidence;
   if (d.version === 2) {
     const j = validateJob(d.job, sources, { brief: typeof d.brief === "string" ? d.brief : "", readSource: ctx.readSource });
     problems.push(...j.problems);
@@ -8936,6 +9374,10 @@ function validateDirection(input, ctx = {}) {
     const h = validateHierarchy(d.hierarchy, d.job, sources);
     problems.push(...h.problems);
     hierarchy = h.pages;
+    const pages = d.hierarchy && typeof d.hierarchy === "object" && !Array.isArray(d.hierarchy) ? d.hierarchy : {};
+    const recorded = Object.entries(pages).filter(([k, p]) => PAGE_TYPES.includes(k) && p && typeof p === "object" && p.confidence !== void 0);
+    for (const [page, p] of recorded) problems.push(...validateConfidence(page, p.confidence, d.job, sources));
+    if (recorded.length) confidence = assessConfidence(d.hierarchy, d.job, { snapshot: ctx.snapshot, snapshotPage: ctx.page });
     if (ctx.snapshot) problems.push(...checkOrder(d.hierarchy?.[ctx.page ?? "home"], ctx.page ?? "home", ctx.snapshot, ctx.strict));
   }
   if (ctx.estate?.length) {
@@ -8952,6 +9394,7 @@ function validateDirection(input, ctx = {}) {
     valid: problems.every((p) => p.severity !== "error"),
     problems,
     decided,
+    ...confidence ? { confidence } : {},
     layers: { job, hierarchy, tokens: { decided, total: CHOICE_KEYS.length }, complete: complete && problems.every((p) => p.severity !== "error") }
   };
 }
@@ -9509,6 +9952,7 @@ function retrofitPlan(report2, direction) {
 export {
   ACCENT_SCALE,
   ACCENT_SHARED,
+  ADDITIONS,
   AI_PHRASES,
   AI_SOURCE_TYPES,
   AI_VIOLET,
@@ -9517,8 +9961,11 @@ export {
   BUZZWORDS,
   CATALOGUE,
   CATALOGUE_VERSION,
+  CHANGE_CLASSES,
+  CHANGE_STEPS,
   CHOICE_KEYS,
   COMPONENT_ROLES,
+  CONFIDENCE_LENSES,
   CONSIDERATION,
   CONTENT_FEATURES,
   CONVENTION,
@@ -9535,6 +9982,7 @@ export {
   EASE_TUPLE,
   EDGE_STEP,
   ESTATE_VERSION,
+  EVIDENCE_KINDS,
   EXIT_RATIO,
   FINGERPRINT_VERSION,
   FLAGGED_TARGET,
@@ -9550,6 +9998,7 @@ export {
   HOUSE_TYPE,
   HUMAN_TYPICAL_TARGET,
   IMAGERY_TELLS,
+  INSPECTED_KINDS,
   JSON_SCHEMA_VERSION,
   LABELS2 as LABELS,
   LEXICAL_FEATURES,
@@ -9570,6 +10019,8 @@ export {
   PROFILE_MEASURED,
   PROFILE_PARAGRAPHS,
   PROMO_BADGE,
+  PROOF_DEPTHS,
+  PROOF_KINDS,
   PROOF_NAMES,
   PROPOSED,
   PROVENANCE_SCAN_BYTES,
@@ -9583,7 +10034,9 @@ export {
   REGISTER_IDS,
   RENDERED_PATHS,
   RENDERED_TELLS,
+  REPORTED_KINDS,
   REVEAL_LIMIT,
+  REVIEW_BASES,
   REVIEW_PHRASES,
   SAMPLES_PER_SEGMENT,
   SCALE,
@@ -9612,12 +10065,15 @@ export {
   TYPE_STEPS,
   TYPICAL_AT,
   VAGUE_WORDS,
+  VIEWPORTS,
   accentFork,
   addSite,
   apcaContrast,
   applyBaseline,
   applyHouseGate,
   applySeverity,
+  assessConfidence,
+  assessReview,
   auditSnapshot,
   bandOf,
   briefTerms,
@@ -9705,6 +10161,7 @@ export {
   isCategoryLabel,
   isCream,
   isFlagged,
+  isStructural,
   jobWords,
   layoutDistance,
   lexicalOf,
@@ -9775,9 +10232,11 @@ export {
   typeFeatureTokens,
   typicality,
   unprovenClaims,
+  validateConfidence,
   validateDirection,
   validateHierarchy,
   validateJob,
+  viewportOf,
   visibleText,
   visualMeasures,
   vocabulary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/craft",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "private": false,
   "description": "The Doman Digital house craft standard as numbers: OKLCh colour ramps that snap to existing anchors, derived semantic tokens with measured WCAG and APCA contrast, one shared motion vocabulary for CSS and JS, and a base stylesheet. Zero dependencies.",
   "license": "Apache-2.0",
@@ -48,11 +48,13 @@
     "./package.json": "./package.json",
     "./craft.css": "./css/craft.css",
     "./craft.tailwind.css": "./css/craft.tailwind.css",
-    "./art-direction.schema.json": "./art-direction.schema.json"
+    "./art-direction.schema.json": "./art-direction.schema.json",
+    "./design-review.schema.json": "./design-review.schema.json"
   },
   "files": [
     "CHANGELOG.md",
     "art-direction.schema.json",
+    "design-review.schema.json",
     "CHARACTER.md",
     "COPY.md",
     "LICENSE",