@domandigital/craft 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @domandigital/craft
 
+## 0.15.0
+
+### Minor Changes
+
+- 74f0aed: Add art direction version 2 with customer job maps, per-page hierarchy and
+  reasons tied to the job. Record and compare declared directions before build,
+  print job-only research prompts, and validate order and token drift against
+  saved snapshots or preview URLs. Existing version 1 files remain valid with a
+  warning; the report requires all three layers before marking reasons decided.
+
+  Estate entries registered before build have no fingerprint. `EstateSite.fingerprint`
+  is now optional; rendered comparisons skip those entries until a snapshot is added.
+
+- 006c97d: Expose pure shape measurements for short copy and add resumable calibration
+  tooling with frozen human baselines. This is a measurement foundation: no new
+  copy tells or blocking rules ship. Incomplete generation cannot approve a
+  feature for the catalogue.
+
+## 0.14.0
+
+### Minor Changes
+
+- 8686cf1: Phase N, specificity. `specificity(text, brief?)` counts what only this business could have written: names, places, numbers, prices, dates, contact details and trade nouns, with Title Case and shouted lines read without their capitals and stock figures ("24/7", "100%", "5-star") masked. A brief's own terms are recognised wherever they appear. Snapshots now record each section's `text` and the `firstScreenText` a visitor reads before scrolling, leaving out navigation, buttons, links and footers. Two new tells, both `warn`: `generic-hero-claim` (copy and rendered, home page only: the headline and the line under it name nothing particular) and `unproven-claim` (rendered: a claim of standing such as "trusted" or "fully qualified" with no review, rating, registration number or accreditation in its section or the one either side). `craft copy compare <ours> --competitor <theirs>` lists the hero and service sentences on each page that hold no specific the other page lacks. The catalogue table no longer prints "rendered + rendered" for rendered-only tells.
+
 ## 0.13.0
 
 ### Minor Changes

package/CHARACTER.md

@@ -9,16 +9,15 @@ Inter, a glass card over the hero, a strip of logos, three icon cards, every
 section fading up on scroll. None of those is wrong. Together they say nobody
 chose anything.
 
-## Change the look, not the page grammar
+## Decide the page grammar; never reward strangeness
 
-First impressions favour pages that look typical for their category (Tuch et
-al., 2012). So this standard **never rewards strangeness**. Navigation, where
-the call to action sits, reading order and legibility stay conventional. They
-remain the job of STANDARD.md and the page audit.
+Section order, the primary action and what leads are decisions with reasons
+tied to the visitor's job. A conventional order is allowed and never penalised.
+What fails is an order nobody chose. Navigation, legibility and speed remain
+the floor in STANDARD.md and the page audit.
 
-Character goes into the surface: the display face, the accent, the shape
-language, the motif, the one signature moment. That is where a model's defaults
-show, and where a real business has something of its own to draw on.
+Character also comes from the display face, accent, shape, motif and one
+signature moment, with evidence from the client's world.
 
 ## Three signals, and a reason behind every choice
 
@@ -57,36 +56,222 @@ cleaned and should stay clean.
 
 ## Declaring the direction
 
-`art-direction.json` at the site root records the seven expressive choices
-(accent, ground, display face, body face, shape, motif, signature moment), the
-sources in the client's world they come from, and why. Layout and navigation
-are not choices here: they stay conventional.
+Version 2 of `art-direction.json` records three layers in order:
+
+1. **Job.** What the visitor needs to do, under what pressure, with the
+   functional, emotional and social sides shown by reviews, enquiries,
+   conversations or search evidence. Quote the customer's words and record
+   whether consideration is low, considered or high, with evidence.
+2. **Hierarchy.** For each page type, decide the primary action and its
+   positions, the section order, what leads and the visitor's journey. Each
+   reason must use this client's job. The primary action reason also names the
+   consideration level or an objection that explains where the ask sits.
+3. **Tokens.** The seven expressive choices (accent, ground, display, body,
+   shape, motif, signature), each with evidence from the client's world.
+
+This fictional example is also the executable fixture at
+`src/__tests__/fixtures/direction-v2.json`. Its customer quotes are invented
+fixture data, not research to reuse for a real client.
 
 ```json
 {
-  "version": 1,
-  "client": "RMP Electrical",
-  "brief": "A two-person electrical contractor in Brackley doing rewires and EV chargers.",
+  "version": 2,
+  "client": "Copper Lane Electrical (fictional)",
+  "brief": "A local electrician in Brackley repairing dangerous electrical faults for tenants and homeowners.",
   "sources": [
-    { "id": "van", "kind": "livery", "note": "The Transit van, bottle green with cream sign-writing.", "path": "brand/van.png" }
+    {
+      "id": "review",
+      "kind": "review",
+      "note": "The socket started sparking tonight. I need the fault fixed today without being overcharged. I want an exact call-out price before I ring. I need to reassure my landlord that the repair is safe."
+    },
+    {
+      "id": "van",
+      "kind": "livery",
+      "note": "The van carries copper lettering on white panels, with square painted borders.",
+      "colours": [
+        "#a64720",
+        "#ffffff"
+      ],
+      "lettering": "Square slab lettering and compact supporting text."
+    }
   ],
+  "job": {
+    "statement": {
+      "verb": "find",
+      "object": "an electrician who can repair a dangerous sparking socket",
+      "context": "tonight without being overcharged for the call-out"
+    },
+    "functional": {
+      "value": "The socket started sparking tonight and needs the fault fixed today.",
+      "evidence": [
+        "review"
+      ]
+    },
+    "emotional": {
+      "value": "They worry about being overcharged and want an exact call-out price.",
+      "evidence": [
+        "review"
+      ]
+    },
+    "social": {
+      "value": "They need to reassure their landlord that the repair is safe.",
+      "evidence": [
+        "review"
+      ]
+    },
+    "consideration": {
+      "value": "low",
+      "because": "The socket started sparking tonight, leaving minutes to arrange the repair.",
+      "evidence": [
+        "review"
+      ]
+    },
+    "objections": [
+      "being overcharged for the call-out",
+      "not knowing whether the repair is safe"
+    ],
+    "language": [
+      "The socket started sparking tonight",
+      "I want an exact call-out price before I ring"
+    ],
+    "evidence": [
+      "review"
+    ]
+  },
+  "hierarchy": {
+    "home": {
+      "primaryAction": {
+        "value": "Call for a repair",
+        "positions": [
+          "hero",
+          "footer-cta"
+        ],
+        "because": "The low consideration job needs a sparking socket repaired tonight, so the call is offered immediately and again after the price."
+      },
+      "order": [
+        {
+          "role": "hero",
+          "because": "The sparking socket needs repair tonight, so availability comes first."
+        },
+        {
+          "role": "pricing",
+          "because": "Callers expect a price before they ring, so pricing comes before asking again."
+        },
+        {
+          "role": "footer-cta",
+          "because": "Once the call-out price is clear, they can arrange the socket repair."
+        }
+      ],
+      "lead": {
+        "value": "Socket repairs tonight",
+        "subordinate": [
+          "planned rewires"
+        ],
+        "because": "The dangerous sparking socket is urgent, so tonight repairs lead ahead of planned rewires."
+      },
+      "journey": [
+        {
+          "stage": "reassure",
+          "because": "The dangerous socket needs a safe repair, so reassure the tenant first."
+        },
+        {
+          "stage": "act",
+          "because": "Once the call-out price is clear, arrange the repair before tonight ends."
+        }
+      ]
+    }
+  },
   "choices": {
     "accent": {
-      "value": "#1f4d3a",
-      "because": "The bottle green is the van's own paint, and the van is what people in Brackley recognise.",
-      "evidence": ["van"]
+      "value": "#a64720",
+      "because": "The van carries copper lettering, so the same copper colour marks calls to action.",
+      "evidence": [
+        "van"
+      ]
+    },
+    "ground": {
+      "value": "#ffffff",
+      "because": "The van has white panels behind its lettering, so the page ground follows those panels.",
+      "evidence": [
+        "van"
+      ]
+    },
+    "display": {
+      "value": "Roboto Slab",
+      "because": "The square slab lettering on the van gives headlines their squared forms.",
+      "evidence": [
+        "van"
+      ]
+    },
+    "body": {
+      "value": "Source Sans 3",
+      "because": "The compact supporting text on the van keeps longer details readable at small sizes.",
+      "evidence": [
+        "van"
+      ]
+    },
+    "shape": {
+      "value": "square corners",
+      "because": "The painted borders on the van are square, so the buttons keep those corners.",
+      "evidence": [
+        "van"
+      ]
     }
-  }
+  },
+  "exceptions": []
 }
 ```
 
-`craft direction validate` applies the reason rule. A choice is decided only
-when its reason is at least a sentence, cites a declared source, and mentions
-what that source shows (naming only the colour does not count). It rejects a
-preference ("the client likes it"), a mood board (two or more of modern,
-clean, premium, elegant and the rest), and a value on the tell catalogue
-without an exception carrying the same reason. Given a snapshot, it warns
-where the page does not show what the file declares.
+`craft direction validate` checks each layer and reports its decisions
+separately. The job and every declared page hierarchy must be complete, with
+at least five of seven tokens decided, before the reason signal can pass in
+`craft report`. Version 1 files remain valid with a warning and cannot settle
+that signal until their job and hierarchy have been recorded.
+
+A reason needs at least eight words. Token reasons cite a declared source and
+mention what it shows; job parts cite customer voice. Hierarchy reasons use
+content words from the job. This is a wording check, not a semantic model:
+review whether each reason actually explains the decision. Preferences, mood
+boards, proposals and category defaults such as "industry standard" or
+"a familiar layout" fail. "Callers expect a price before they ring" can pass
+when it answers this job's objection about being overcharged.
+
+A `reference` source records its outside category in `category`; a reference
+from the client's trade or a competitor's website fails. URL references warn
+that their category still needs review. The validator cannot identify a
+competitor from an arbitrary URL alone.
+
+Start research with `craft direction research --brief "<who, where, what>"`.
+It prints job questions and explicitly forbids descriptions of category
+websites or visual inspiration from them. `--visual` adds a separate prompt
+for references from outside the category. It does not call a model.
+
+CTA positions are a list: one or repeated asks are both valid. No universal
+position, F/Z pattern or fixed hero checklist is imposed. Snapshots measure
+vertical section order, not gaze paths; the evidence does not establish a
+universal CTA placement rule.
+
+```bash
+craft direction init --client "Copper Lane" --brief "<who, where, what>"
+craft direction validate --direction art-direction.json
+craft estate add --id copper-lane --direction art-direction.json --estate estate.json
+craft direction validate --estate estate.json
+craft direction validate --snapshot http://localhost:3000 --page home --strict
+craft estate compare --estate estate.json --directions
+```
+
+`--snapshot` accepts a saved snapshot, staging URL or live URL. It checks the
+hierarchy entry selected by `--page` (home by default) against section roles,
+and checks token values against the fingerprint. Drift warns; `--strict`
+makes drift fail. A snapshot without section roles says order is unmeasured.
+
+Directions can be registered before a site renders. These entries have no
+fingerprint and are omitted from rendered comparisons until a snapshot is
+added. `--directions` ranks declared pairs and names shared colours, fonts,
+shape and order. It is advisory, including under `--strict`, until calibrated;
+sharing a conventional order is a prompt to review reasons, not a verdict.
+Accent and ground use the rendered comparison's shared thresholds, ΔE_OK
+0.06 and 0.03. The calibration notes are in ROADMAP.md.
 
 It also reads the display and body faces against the licence register
 (`src/direction/licences.ts`, exported as `licences.json`) and warns on a face
@@ -103,7 +288,7 @@ choices decided.
 
 `craft direction propose` reads the dominant colours off each source's PNG
 photo, ranks accent candidates away from the reflex violet band and from the
-rest of the estate (`--estate` a folder of snapshots), and drafts choices.
+rest of the estate (`--estate` a folder of snapshots or estate register), and drafts choices.
 Every draft reason starts `PROPOSED:`, which validate rejects: a person looks
 at the van, agrees the green is the van's green, and says so in their own
 words.
@@ -250,6 +435,52 @@ abstract blob from a diagram needs an SVG's path data or its pixels, which a
 cross-origin picture does not give the page, and no flag case has been proved
 reliable. It stays on the list until one is.
 
+### Specificity
+
+A page built from no brief could belong to anyone, because the model had
+nothing particular to say. Specificity counts what only this business could
+have written: names, places, numbers, prices, dates, contact details, and
+the nouns of the trade (`TRADE_NOUNS`, a seed list). Two rules keep the
+count honest. A Title Case or shouted line's capitals are not read as names
+("Quality You Can Trust" is not a proper noun), and the figures every site
+uses ("24/7", "100%", "5-star", "No. 1") are masked before counting. A text
+is generic when it has no specific other than trade nouns and fewer than two
+of those: one trade noun ("quality plumbing you can trust") is what every
+competitor also says.
+
+A snapshot now records the page's text: each section's headings,
+paragraphs, list items and quotes (`text`), and what a visitor reads before
+scrolling (`firstScreenText`), leaving out navigation, a header without the
+headline, footers and the words on buttons and links. Two tells read it:
+
+- `generic-hero-claim`: the home page's first screen names nothing
+  particular. Also a copy tell, on a literal `<h1>` and the paragraph under
+  it in the home page's source (a root route file such as `app/page.tsx`, a
+  top-level `index.html`, or a hero or home component). Every other page's
+  headline is a label ("Privacy policy", "Boiler repairs"), not a claim, and
+  is not judged.
+- `unproven-claim`: a claim of standing ("trusted", "fully qualified",
+  "award-winning", "5-star service") with no review, rating, quoted
+  testimonial, registration number or accreditation (by name, or as a logo
+  whose alt text or file name names it) in its section or the one either
+  side.
+
+A brief sharpens the count: its own terms (the business's name, its town,
+its trade) are recognised wherever they appear, even opening a sentence or
+in a shouted heading. The tells run without one. `craft copy compare <ours>
+--competitor <theirs>` uses one, from `--brief`, `art-direction.json` or a
+null model's `null.json`, and lists the hero and service sentences on each
+page that hold no specific the other page lacks: a town both name, or a
+trade noun both use, is shared; the business's name, its prices and its
+jobs are its own. It is a measure for a person to read and always exits 0.
+
+The limits, stated so nobody reads more into a pass than is there: a place
+in a Title Case heading ("Boiler Repairs In Brackley") is not recognised
+without a brief, a headline whose words come from data (`{site.headline}`)
+is not read in source, and "specific" means particular, not true. `craft
+copy claims` is where a figure gets checked. Snapshots taken before craft
+recorded text have none, and neither tell judges them.
+
 ## The counterfactual
 
 A list of tells goes stale; the model does not. So signal 2 asks the model
@@ -622,7 +853,7 @@ Generated from the package. Run `pnpm --filter @domandigital/craft run docs`
 after changing an entry; a test fails until you do.
 
 <!-- craft:catalogue:start -->
-Catalogue version `2026.09.11`, 66 tells.
+Catalogue version `2026.09.12`, 68 tells.
 
 | Id | Gen | Surface | Severity | Tell | Why it is a default |
 | --- | --- | --- | --- | --- | --- |
@@ -682,14 +913,16 @@ Catalogue version `2026.09.11`, 66 tells.
 | `repeated-sentence` | 1 | copy | warn | Repeated sentence | The same sentence on two pages, or the same nine words lightly edited, is one of the strongest signs a document was assembled rather than written. |
 | `heading-shape` | 2 | copy | warn | One heading shape | Headings that all share one shape ('X, and Y', 'X, because Y', 'Keep, rewrite, consolidate, retire') read as a template filled in section by section. |
 | `heading-echo` | 2 | copy | warn | Heading echoed | A heading repeated word for word as the first line under it spends the reader's attention twice on the same words. |
-| `cta-band-stock` | 1 | rendered + rendered | warn | Stock call-to-action band | A full-width coloured band with a centred heading, one line and one or two buttons is what a model closes every section run with. It asks for the booking the same way on every site. |
-| `pricing-trio-popular` | 1 | rendered + rendered | warn | Three-tier pricing with a popular badge | Three price cards with the middle one badged 'Most popular' is the SaaS pricing page, applied to a plumber or a salon whether or not anyone chose the middle option. |
-| `testimonial-avatar-carousel` | 1 | rendered + rendered | warn | Avatar testimonial carousel | Round headshots over quotes in a sliding carousel is the stock testimonial block. Most visitors see the first slide only, and stock or AI faces make every quote read as invented. |
-| `faq-accordion-closer` | 2 | rendered + rendered | warn | FAQ accordion as the closer | Ending the page on a collapsed FAQ, often followed only by a band, is the model's default page ending. The answers a buyer needs are hidden behind clicks at the point they decide. |
-| `stats-row` | 1 | rendered + rendered | warn | Row of big numbers | Three or four large figures in a row (500+ clients, 98% satisfaction, 10 years) is the stock proof block, and the numbers are often round, unsourced or invented. |
-| `centred-everything` | 2 | rendered + rendered | warn | Every section centred | When almost every section stacks a centred heading over centred text, the page has no reading line and every block looks like the one before. It is the layout nothing was decided for. |
-| `stock-photo` | 1 | rendered + rendered | warn | Stock photography | A picture from a stock library is the picture every other site in the trade can use. It shows a job the client did not do, in a kitchen that is not theirs, and a visitor who has seen it before stops believing the rest. |
-| `stock-avatar` | 1 | rendered + rendered | warn | Stock or placeholder faces | Round portraits from a placeholder-face service or a stock library next to reviews make every quote read as invented, and some of those faces are generated people who do not exist. |
-| `ai-image` | 2 | rendered + rendered | warn | Generated image | The file itself says a model made it (its XMP or Content Credentials name a trained-model source). A generated picture stands in for work the client did not photograph, and anyone can read the label. |
-| `no-real-imagery` | 1 | rendered + rendered | warn | No photograph on the page | A page with no photograph at all, only icons and illustrations, is the page a model builds when it has no assets. Icon tiles stand in for the evidence a buyer looks for: the work, the premises, the people. |
+| `generic-hero-claim` | 1 | copy + rendered | warn | Headline that fits any business | The first thing a visitor reads on the home page names no place, no person, no price and no job, so it would fit every competitor's site unchanged. A model writes it when it has nothing particular to say. |
+| `cta-band-stock` | 1 | rendered | warn | Stock call-to-action band | A full-width coloured band with a centred heading, one line and one or two buttons is what a model closes every section run with. It asks for the booking the same way on every site. |
+| `pricing-trio-popular` | 1 | rendered | warn | Three-tier pricing with a popular badge | Three price cards with the middle one badged 'Most popular' is the SaaS pricing page, applied to a plumber or a salon whether or not anyone chose the middle option. |
+| `testimonial-avatar-carousel` | 1 | rendered | warn | Avatar testimonial carousel | Round headshots over quotes in a sliding carousel is the stock testimonial block. Most visitors see the first slide only, and stock or AI faces make every quote read as invented. |
+| `faq-accordion-closer` | 2 | rendered | warn | FAQ accordion as the closer | Ending the page on a collapsed FAQ, often followed only by a band, is the model's default page ending. The answers a buyer needs are hidden behind clicks at the point they decide. |
+| `stats-row` | 1 | rendered | warn | Row of big numbers | Three or four large figures in a row (500+ clients, 98% satisfaction, 10 years) is the stock proof block, and the numbers are often round, unsourced or invented. |
+| `centred-everything` | 2 | rendered | warn | Every section centred | When almost every section stacks a centred heading over centred text, the page has no reading line and every block looks like the one before. It is the layout nothing was decided for. |
+| `stock-photo` | 1 | rendered | warn | Stock photography | A picture from a stock library is the picture every other site in the trade can use. It shows a job the client did not do, in a kitchen that is not theirs, and a visitor who has seen it before stops believing the rest. |
+| `stock-avatar` | 1 | rendered | warn | Stock or placeholder faces | Round portraits from a placeholder-face service or a stock library next to reviews make every quote read as invented, and some of those faces are generated people who do not exist. |
+| `ai-image` | 2 | rendered | warn | Generated image | The file itself says a model made it (its XMP or Content Credentials name a trained-model source). A generated picture stands in for work the client did not photograph, and anyone can read the label. |
+| `no-real-imagery` | 1 | rendered | warn | No photograph on the page | A page with no photograph at all, only icons and illustrations, is the page a model builds when it has no assets. Icon tiles stand in for the evidence a buyer looks for: the work, the premises, the people. |
+| `unproven-claim` | 1 | rendered | warn | Claim with no proof next to it | "Trusted", "fully qualified" and "award-winning" ask the visitor to take the business's word for it. A page built with no reviews and no registration number makes the claim anyway, with nothing beside it. |
 <!-- craft:catalogue:end -->

package/COPY.md

@@ -102,6 +102,7 @@ person reading decides which instance earns its place.
 | `inline-label-list` | three or more bullets in a row opening "**Label:**", where the label repeats the line |
 | `prompt-context` | "This article uses the attached Perplexity research file as the primary source", "the attached research is right to say", "the attached brief asks": the model naming what it was given. A web page has no attachment. **Zero in anything published** |
 | `placeholder` | "[Insert client name]", lorem ipsum, `TODO_PLACEHOLDER`. Fine in a draft commit; **zero in anything delivered** |
+| `generic-hero-claim` | on the home page (a root route file, a top-level `index.html`, or a hero or home component), a literal `<h1>` and the paragraph under it that name no place, person, number, price or job: "Quality you can trust", "Your vision, our expertise". One trade noun is not enough ("quality plumbing"); two are ("boiler and radiator repairs"). Also read on the rendered first screen by `craft audit` |
 
 ### Style is not evidence
 
@@ -218,6 +219,10 @@ Hyphenated compounds count as one word. Not automated.
   sourced or UNSOURCED. A claim is sourced, corrected or cut, never re-cited
   from memory. The copy check cannot do this part: a false figure in clean
   prose passes every tell.
+- **Proof sits next to the claim it backs.** "Trusted", "fully qualified",
+  "award-winning" and "5-star service" need a review, a rating or an
+  accreditation in the same section or the one either side of it. `craft
+  audit` reports each one that has none (`unproven-claim`, a warning).
 
 ## CTA rule
 

package/README.md

@@ -94,6 +94,24 @@ reason, in `art-direction.json`:
 { "exceptions": [{ "tell": "ai-violet", "because": "Violet is on the van, the cards and the fascia." }] }
 ```
 
+Art direction v2 records the customer's job, a hierarchy for each page type,
+and seven expressive tokens, with reasons and evidence. Begin with job
+research, then hierarchy, then tokens:
+
+```bash
+npx craft direction research --brief "An electrician in Brackley repairing dangerous faults for local households"
+npx craft direction init --client "Copper Lane" --brief "<who, where, what they do>"
+npx craft direction validate --estate estate.json
+npx craft estate add --id copper-lane --direction art-direction.json --estate estate.json
+npx craft estate compare --estate estate.json --directions
+npx craft direction validate --snapshot http://localhost:3000 --page home --strict
+```
+
+`--snapshot` accepts saved files and preview or production URLs. Drift fails
+with `--strict`; declared estate comparisons stay advisory. Version 1 files
+still validate with a warning. See [CHARACTER.md](./CHARACTER.md) for the full
+v2 example and the meaning of each layer.
+
 ### In CI
 
 ```bash
@@ -163,7 +181,7 @@ console.log(formatReport(report, "craft scan"));
 
 ## The anchor guarantee
 
-Every hex you pass in comes back out unchanged — the same string, byte for byte.
+Every hex you pass in comes back out unchanged, the same string, byte for byte.
 That is what lets a live site adopt this without a single pixel moving. Only the
 steps you never picked by hand are generated.