page-foundry 2.9.1

package/skills/page-foundry/references/ship-gates.md

@@ -0,0 +1,224 @@
+# Ship Gates
+
+Run every gate. Report results as a pass/fail table plus the MECLABS score. A failed gate means fix and re-run, not ship with a caveat.
+
+Handoff mode: gates 1, 2, and 8 run before the package is delivered; gates 3, 4, 5, 6, and 7 become acceptance criteria in the package and run in full when the built asset comes back, along with a re-run of 1 and 2 on the rendered page. Details in `references/handoff.md`.
+
+## Gate 1: Conversion audit
+
+- [ ] 5-second test passes on a cold read (headline + subhead + CTA label only).
+- [ ] Primary headline within budget (target under ~44 chars, ceiling 70).
+- [ ] Exactly one primary CTA action on the page; repeats are identical in wording and destination.
+- [ ] Every CTA instance has a proof element within one viewport.
+- [ ] campaign-landing only: no site navigation, hero language matches the traffic source.
+- [ ] Forms: every field beyond name/email has a written justification in the spec.
+- [ ] MECLABS heuristic scored (rubric in conversion-rules.md); flagged factors (M/V/I low, F/A high) addressed or explicitly accepted.
+- [ ] Red-team read: one simulated skeptical reader per segment x entry state from the brief walks the page; every reader must reach the CTA. Any "not for me" exit by a qualified reader is a failure (conversion rule 10). Log bounce points and fix.
+
+## Gate 2: Voice
+
+- [ ] `python3 scripts/voice_scan.py <files>` returns zero FAILs (banned phrases, em/en dashes in prose).
+- [ ] Pattern pass done: every `AI language pattern` WARN resolved (negative parallelism "not X, it's Y", copula avoidance "serves as", tailing negation "no X, no Y", significance inflation, authority trope, three-verb-clause runs, parallel-list uniformity). **The humanizer skill was invoked on the final copy, its rewrites applied, and that is recorded on the `humanizer` line below.** The scanner passing is necessary but not sufficient: structural uniformity across separate elements (a parallel roster) is beyond regex, so a scanner PASS with no humanizer pass is an incomplete Gate 2, not a clean one.
+- [ ] Read-aloud pass done: no sentence the owner would not say to a client across a table.
+- [ ] No fabricated specificity: every number, name, and quote traces to the proof inventory.
+
+## Gate 3: Accessibility (WCAG 2.2 AA spot checks)
+
+- [ ] One `h1`; heading levels do not skip.
+- [ ] Landmarks present (`nav`, `main`, `footer`); links and buttons are real `a`/`button` elements; icon-only controls carry an `aria-label`.
+- [ ] Text contrast 4.5:1 (3:1 for large text and UI components); CTA buttons included.
+- [ ] Visible keyboard focus on all interactive elements (`:focus-visible`), logical tab order, and focus never obscured (WCAG 2.2 SC 2.4.11).
+- [ ] Touch targets at least 24x24px (WCAG 2.2 SC 2.5.8); 44px preferred for primary actions.
+- [ ] Every informative image has real alt text and explicit `width`/`height` (CLS); decorative images have empty alt.
+- [ ] No content conveyed by color alone; `prefers-reduced-motion` respected; motion animates only `transform`/`opacity`, never `transition: all`.
+- [ ] Form inputs have programmatic labels plus correct `type`/`inputmode`/`autocomplete`; async status changes use `aria-live`.
+- [ ] If the page has auth, no step forces a memory or transcription test with no easier alternative (WCAG 2.2 SC 3.3.8).
+
+## Gate 4: Performance
+
+- [ ] Total transfer under ~1MB; CSS+JS under ~200KB.
+- [ ] Images sized to display dimensions, modern formats (WebP/AVIF), lazy-loaded below the fold.
+- [ ] Fonts: system stack, or at most two self-hosted files, preloaded, `font-display: swap`.
+- [ ] No render-blocking third-party scripts; analytics deferred.
+- [ ] Target: LCP under ~2s on a mid-range phone. If a Lighthouse run is possible in the environment, run it and record the score.
+
+## Gate 5: Render review
+
+- [ ] Render the page and look at it: screenshot at 390px and 1440px via Playwright, headless Chrome, or gstack `/design-review` when available. Critique the screenshots against the chosen design direction, the anti-slop list, and (when installed) the web-design-guidelines rules; fix anything a cold viewer would flag in five seconds (cramped hero, wall of gray, broken wrap, invisible CTA).
+- [ ] If no render tool exists in the environment, mark this gate N/A in the report and tell the user to eyeball both widths before deploy. Never silently skip it; an unrendered page is unreviewed design.
+
+## Gate 6: AI discovery and meta
+
+- [ ] JSON-LD schema present and valid for the archetype (templates below).
+- [ ] `llms.txt` present at the site root (template below).
+- [ ] `robots.txt` does not `Disallow` the AI crawlers that drive citations: `GPTBot`, `ChatGPT-User`, `PerplexityBot`, `ClaudeBot`, `anthropic-ai`, `Google-Extended`, `Bingbot`. Blocking one loses that engine's citation; only `CCBot` is safe to block. An AI-discovery gate that passes while `ClaudeBot` is disallowed is a false pass.
+- [ ] Page copy is machine-extractable: the primary answer sits in a self-contained 40 to 60 word block near the top, key facts are in real text (not baked into images), and comparisons/FAQs use plain markup.
+- [ ] For archetypes with public pricing (saas-homepage, course-sales, membership-community), a machine-readable `/pricing.md` (or `/pricing.txt`) is present for agentic buyers.
+- [ ] `<title>` and meta description written to the same standard as page copy (voice rules apply), and short enough not to truncate.
+- [ ] Open Graph + Twitter card meta complete, with a real OG image (1200x630).
+- [ ] Canonical URL set; favicon present.
+
+Note: Google does not consume `llms.txt`; it helps ChatGPT, Claude, and Perplexity. Keep it, and do not rely on it for Google.
+
+## Gate 7: Measurement
+
+- [ ] Conversion event defined: the form destination (ESP, endpoint) records source/medium, or the user has consciously declined measurement.
+- [ ] UTM convention stated for every planned traffic source, so campaign performance is attributable from day one.
+- [ ] Analytics: privacy-respecting option (Plausible, GoatCounter, or server logs) wired or consciously declined. A gauge-interest page without measurement cannot gauge interest.
+
+## Gate 8: Integrity
+
+- [ ] Zero fabricated testimonials, logos, counts, or statistics.
+- [ ] Zero fabricated technical artifacts or staged scenarios: (a) every command, terminal output, code snippet, config, and file path is real and runnable exactly as shown, or removed; and (b) every terminal, screenshot, console, or UI depicts a real action the user takes and real output they see. Real data in a styled card (the page's own gate report) is fine; a terminal of a script the user never runs is not, even if the script is real. A demo of the product is held to this.
+- [ ] All `[TK]` placeholders resolved: filled with real material, or the section cut.
+- [ ] Any urgency element (deadline, cap) verified real with the user.
+- [ ] Security/privacy claims substantiated by the brief.
+
+---
+
+## Templates
+
+### llms.txt
+
+Place at `/llms.txt`. Markdown, written in the same plain voice as the page.
+
+```markdown
+# {Product Name}
+
+> One-sentence factual description: what it is, who it is for, what it does.
+
+{2-4 sentences of plain factual detail: core capabilities, platform, pricing model, license if OSS.}
+
+## Links
+
+- [Homepage]({url})
+- [Documentation]({docs-url})
+- [Pricing]({pricing-url})
+- [Source]({repo-url})  <!-- OSS only -->
+
+## Facts
+
+- Built by: {person/company}
+- Platform: {web / iOS / Android / CLI / self-hosted}
+- Pricing: {model, starting price, free tier, or license}
+- Data handling: {one factual sentence}
+```
+
+### JSON-LD by archetype
+
+Wrap in `<script type="application/ld+json">` in `<head>`. Fill only fields with real values; omit anything unknown rather than inventing it.
+
+**saas-homepage / mobile-app** (`SoftwareApplication`):
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "{Product}",
+  "description": "{factual one-liner}",
+  "url": "{url}",
+  "applicationCategory": "{e.g. SecurityApplication, BusinessApplication}",
+  "operatingSystem": "{Web, iOS, Android}",
+  "offers": {
+    "@type": "Offer",
+    "price": "{0 or starting price}",
+    "priceCurrency": "USD"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "{real only}",
+    "ratingCount": "{real only}"
+  },
+  "publisher": { "@type": "Organization", "name": "{Company}", "url": "{company-url}" }
+}
+```
+
+Omit `aggregateRating` entirely unless the numbers are real and public.
+
+**oss-project** (`SoftwareSourceCode`):
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareSourceCode",
+  "name": "{Project}",
+  "description": "{factual one-liner}",
+  "codeRepository": "{repo-url}",
+  "programmingLanguage": "{language}",
+  "license": "https://spdx.org/licenses/{SPDX-ID}",
+  "author": { "@type": "Person", "name": "{maintainer}" }
+}
+```
+
+**campaign-landing with FAQ section** (add alongside the page's primary type):
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "{question as it appears on the page}",
+      "acceptedAnswer": { "@type": "Answer", "text": "{answer as it appears on the page}" }
+    }
+  ]
+}
+```
+
+FAQ schema must mirror the visible page content exactly; do not add schema-only Q&A.
+
+**course-sales / membership-community / dated webinar campaign-landing** (`Event`; use for a page selling a scheduled cohort, workshop, or live event):
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Event",
+  "name": "{Event}",
+  "description": "{factual one-liner}",
+  "startDate": "{ISO 8601, e.g. 2026-09-01T17:00-07:00}",
+  "endDate": "{ISO 8601}",
+  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
+  "eventStatus": "https://schema.org/EventScheduled",
+  "location": { "@type": "VirtualLocation", "url": "{join or info url}" },
+  "organizer": { "@type": "Organization", "name": "{Company}", "url": "{url}" },
+  "offers": {
+    "@type": "Offer",
+    "price": "{price}",
+    "priceCurrency": "USD",
+    "url": "{registration url}",
+    "availability": "https://schema.org/InStock"
+  }
+}
+```
+
+Omit `endDate` and `offers` fields you cannot fill with real values; never invent a date, price, or seat count.
+
+**homepage / personal-home** (optional, add alongside the primary type): a `WebSite` with `potentialAction` SearchAction when the site has search, and a standalone `Organization` (name, url, logo, sameAs social links) so the brand resolves as an entity.
+
+### Gate report format
+
+```
+## Ship gates: {product} / {archetype}
+
+| Gate | Result | Notes |
+|---|---|---|
+| Conversion audit | PASS | MECLABS C = {n} (M{n} V{n} I{n} F{n} A{n}) |
+| Voice scan | PASS | 0 hits across {n} files |
+| Accessibility | PASS | |
+| Performance | PASS | {transfer size}, {LCP if measured} |
+| Render review | PASS / N/A | {widths checked, or why N/A} |
+| AI discovery | PASS | schema valid, llms.txt present |
+| Measurement | PASS | {conversion event, UTM, analytics or declined} |
+| Integrity | PASS | {n} TK items resolved/cut |
+
+Humanizer: {invoked on final copy — yes/no; one line on what it changed (e.g. "broke two three-verb runs, varied a 6-item roster"), or "not run" which makes Gate 2 incomplete}
+
+Degraded phases: {any phase that ran on a reference-file fallback because its companion was missing or declined, named with the companion it lacked; "none, all companions present" otherwise. A degraded run is a partial execution, and the owner is told which skill would improve it.}
+
+Open items for the owner: {real proof to collect, urgency to verify, etc.}
+```
+
+---
+
+_Provenance: reconciled 2026-07-07 against marketingskills 2.3.0 (ai-seo, schema, cro) and web-design-guidelines (vercel-labs, live ruleset). JSON-LD templates verified current against schema.org; accessibility bumped to WCAG 2.2 AA. The MECLABS heuristic is external (rubric in conversion-rules.md), not from the cro companion. Re-reconcile when those companions or the schema.org / WCAG baselines change._

package/skills/page-foundry/references/voice.md

@@ -0,0 +1,204 @@
+# Voice
+
+This file governs every word that ships on a page, and it is the single source of truth for the mechanical scanner (`scripts/voice_scan.py` parses the blocks marked `scan:` below). Edit this file, or run the Voice wizard in SKILL.md, and both the writing guidance and the scanner change together.
+
+**First run:** this file ships with a neutral default register. Run the Voice wizard ("set up my voice") to make it yours, or edit the sections below directly; the scanner follows this file, so guidance and enforcement change together. The AI-flagged vocabulary list near the bottom is owner-independent; keep it unless you have a specific reason not to. An owner's saved voice file can be dropped over this one at any time (overlay install).
+
+<!-- voice-config
+owner: default
+em_dash: fail
+en_dash: fail
+max_exclamations: 1
+-->
+
+## Register (owner-configurable; the wizard rewrites this section)
+
+Neutral default until an owner configures their own:
+
+- Plain language, short sentences, active voice. Write like a competent person explaining something to a peer.
+- Specific beats clever. Concrete nouns and real numbers beat adjectives every time.
+- Claims are checkable. If no reader could prove a sentence wrong, it is not saying anything; cut it.
+- Describe the work; do not praise it. "Scans your whole estate in 20 minutes" beats "blazing-fast industry-leading scanning".
+- One idea per sentence. If a line needs a second read, split it.
+- Humor only if the owner's brand uses it; the default is none.
+
+## Punctuation (defaults; owners change these via the wizard, enforced via voice-config above)
+
+- **No em dashes, no en dashes in prose.** Use commas, semicolons, periods, or restructure. Hyphens in compound words are fine. Numeric ranges use "to".
+- No exclamation points in body copy beyond the configured maximum (currently 1 per page, and only if the brand uses them at all).
+- Sentence case for headings and buttons unless the design direction states otherwise.
+
+## Banned list
+
+Zero FAIL occurrences in shipped copy. The scanner enforces the lists below mechanically; the intent is broader than the literal list: anything that pattern-matches to AI-generated or generic-marketing voice is out, even if not listed. One term per line; lines starting with `#` are comments.
+
+<!-- scan:banned-phrases -->
+# AI-flagged vocabulary
+delve
+dive deep
+deep dive
+robust
+streamline
+streamlined
+seamless
+seamlessly
+holistic
+cutting-edge
+cutting edge
+state-of-the-art
+state of the art
+game-changer
+game changer
+game-changing
+revolutionize
+revolutionary
+transformative
+unlock
+unleash
+elevate
+empower
+empowering
+supercharge
+harness
+foster
+realm
+tapestry
+testament
+embark
+beacon
+paradigm
+synergy
+effortless
+effortlessly
+frictionless
+innovative
+world-class
+best-in-class
+industry-leading
+next-level
+turbocharge
+skyrocket
+crucial
+pivotal
+furthermore
+moreover
+in today's
+in an era of
+in the ever-evolving
+ever-evolving
+look no further
+take it to the next level
+at the end of the day
+digital landscape
+threat landscape
+optimize
+optimise
+utilize
+utilise
+facilitate
+comprehensive
+groundbreaking
+bolster
+underscore
+unveil
+nuanced
+multifaceted
+intricate
+paramount
+# AI openers, transitions, and closers
+at its core
+that being said
+it's worth noting that
+it is worth noting that
+this begs the question
+in conclusion
+to sum up
+in essence
+with that in mind
+imagine a world where
+a myriad of
+a plethora of
+shed light on
+pave the way for
+# Empty marketing phrases
+no fluff
+no hype
+no bs
+real talk
+the ultimate
+you'll ever need
+join the revolution
+don't miss out
+trusted by thousands
+# Hedge filler
+arguably
+essentially
+basically
+ultimately
+undoubtedly
+simply put
+needless to say
+it goes without saying
+as you may know
+<!-- /scan:banned-phrases -->
+
+Words banned only in figurative use are listed below; the scanner reports them as WARN for human judgment (it cannot do part-of-speech tagging, and some have legitimate literal uses, like "leverage" as a noun).
+
+<!-- scan:judgment-words -->
+navigate
+leverage
+landscape
+journey
+ecosystem
+intuitive
+vital
+enhance
+<!-- /scan:judgment-words -->
+
+## AI language patterns
+
+A word list catches vocabulary; it cannot catch grammar. The tells that most give AI writing away are structural, so the gate checks patterns too. These fire as WARN; the copywriter reviews and rewrites each in Phase 3. The `scan:patterns` block below is the machine-readable subset; the Phase 3 pattern pass and the humanizer skill catch the rest that a regex cannot.
+
+Patterns to kill on sight (from Wikipedia's "Signs of AI writing" and the seo-audit ai-writing-detection list):
+
+- **Negative parallelism.** "It's not just X, it's Y." "Not only X but also Y." State the positive claim once.
+- **Tailing negation fragments.** A sentence ending in a tacked-on "no guessing," "no wasted motion," "not a hunch." Write it as a real clause or cut it.
+- **Copula avoidance.** "serves as," "stands as," "functions as," "acts as a." Use "is" or "are."
+- **Forced rule of three.** Three parallel items or adjectives grouped to sound comprehensive. Use two, or four, or a plain sentence.
+- **Authority tropes.** "the point is," "at its core," "what really matters," "the real question is." Drop the ceremony and state the point.
+- **Significance inflation.** "marks a pivotal moment," "represents a shift," "a testament to." Describe what happened, not its importance.
+- **Superficial -ing tack-ons.** A comma followed by "highlighting / underscoring / showcasing / reflecting..." that adds fake depth. Cut it.
+- **False ranges.** "from X to Y" where X and Y are not on a scale. List the things instead.
+- **Terse noun-pair fragments.** "Seven phases, eight gates." A punchy fragment pairing two counts. Make it a sentence.
+- **Three parallel verb-clauses.** "It runs the skills, gates the result, and hands back a page." Three present-tense verb clauses in a row read as generated. Break the rhythm: two sentences, or vary the verbs and shapes. (Caught by the `three parallel verb-clauses` regex.)
+- **Parallel-list uniformity.** A list where every item opens the same way ("Finds... / Pulls... / Structures... / Writes..."). Uniform openings across a set read as machine-made even when each item is fine alone. Vary the grammatical shape item to item. (The scanner flags a plain prose run of these; a list spread across separate DOM elements with labels is beyond regex, which is why the humanizer pass is a hard gate, not a suggestion.)
+
+<!-- scan:patterns -->
+# AI language patterns, WARN-level. Format: NAME|||REGEX (case-insensitive). Reviewed and fixed in Phase 3.
+negative parallelism|||\bit'?s not (just |merely |simply |only )?[^.,;:]{1,45}[,;:]\s*it'?s\b
+negative parallelism|||\bnot only\b[^.]{1,50}\bbut\b
+tailing negation|||[.;:]\s*no [a-z]{3,},\s*no [a-z]{3,}
+copula avoidance|||\b(serves|stands|functions|acts) as (a |an |the )
+authority trope|||\b(the point is|what really matters|the real question is|the heart of the matter|the deeper point)\b
+significance inflation|||\b(marks|marking|represents|signals) a (pivotal|key|defining|turning|significant) (moment|point|shift|role)\b
+superficial -ing|||,\s+(highlighting|underscoring|emphasizing|showcasing|reflecting|symbolizing|ensuring|fostering|cultivating)\b
+three parallel verb-clauses|||\b[a-z]+s\b[^,.;:!?]{2,60},\s+[a-z]+s\b[^,.;:!?]{2,60},\s+(?:and|then)\s+[a-z]+s\b
+<!-- /scan:patterns -->
+
+## Replacement strategy
+
+Do not synonym-swap a banned word; that produces the same sentence in a cheaper suit. Restructure around the concrete fact the sentence was gesturing at:
+
+- Banned: "Leverage our robust platform to streamline your security workflow."
+- Wrong fix: "Use our powerful platform to simplify your security workflow." (Same empty sentence.)
+- Right fix: "Connect your scanner output once. Triage drops from four hours a week to twenty minutes." (A fact a reader can check.)
+
+If no concrete fact exists to anchor the sentence, the sentence was decoration. Delete it.
+
+## Voice check, beyond the scan
+
+After the mechanical scan passes, read the page top to bottom once and ask of each section: would the owner say this sentence out loud to a client across a table? If it would sound like a brochure, rewrite it as the spoken version.
+
+---
+
+_Provenance: banned and judgment lists reconciled 2026-07-07 against marketingskills 2.3.0 (copywriting, copy-editing) and the seo-audit ai-writing-detection list, which copywriting itself defers to. Re-reconcile when those companions change; keep this list a superset of the AI-writing-detection vocabulary._

package/skills/page-foundry/scripts/voice_scan.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""voice_scan.py: mechanical voice gate for page-foundry.
+
+Rules live in references/voice.md, NOT in this script. The script parses:
+  <!-- voice-config ... -->                key: value lines (em_dash, en_dash,
+                                           max_exclamations; values fail/warn/off
+                                           or an integer)
+  <!-- scan:banned-phrases --> ... <!-- /scan:banned-phrases -->   one per line, FAIL
+  <!-- scan:judgment-words --> ... <!-- /scan:judgment-words -->   one per line, WARN
+  <!-- scan:patterns --> ... <!-- /scan:patterns -->               NAME|||REGEX per line, WARN
+                                           (AI language patterns: negative parallelism,
+                                           copula avoidance, tailing negation, etc.)
+
+Edit voice.md (or run the Voice wizard) and the scanner follows automatically.
+A minimal built-in fallback applies only if voice.md cannot be found.
+
+Scans .html/.md/.txt copy. Strips tags, script/style, and code blocks first so
+code samples and class names don't false-positive.
+
+Usage:
+    python3 voice_scan.py file1.html pages/myproduct/ ...
+    python3 voice_scan.py --rules /path/to/voice.md <targets>
+
+Exit code 0 = clean, 1 = FAIL violations found, 2 = usage error.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+EM_DASH, EN_DASH = "\u2014", "\u2013"
+EXTS = {".html", ".htm", ".md", ".txt"}
+
+FALLBACK = {
+    "banned": ["delve", "robust", "seamless", "game-changer", "cutting-edge",
+               "unlock", "elevate", "streamline", "in today's"],
+    "judgment": ["leverage", "navigate", "journey"],
+    "config": {"em_dash": "fail", "en_dash": "fail", "max_exclamations": 1},
+}
+
+
+def find_rules_file(cli_path):
+    if cli_path:
+        return Path(cli_path)
+    here = Path(__file__).resolve().parent
+    for candidate in (here.parent / "references" / "voice.md",
+                      here / "voice.md",
+                      Path.cwd() / "references" / "voice.md"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def parse_block(text, name):
+    m = re.search(r"<!--\s*scan:" + name + r"\s*-->(.*?)<!--\s*/scan:" + name + r"\s*-->",
+                  text, flags=re.S)
+    if not m:
+        return []
+    items = []
+    for line in m.group(1).splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            items.append(line.lower())
+    return items
+
+
+def parse_patterns(text):
+    """Parse the scan:patterns block. Each line is NAME|||REGEX (case-insensitive).
+    Emits WARN, not FAIL: language patterns are heuristic and need a human read, but
+    the scanner surfaces them so 'not X, it's Y', copula-dodging, and the like cannot
+    slip past a word-only gate. Lines starting with # are comments."""
+    m = re.search(r"<!--\s*scan:patterns\s*-->(.*?)<!--\s*/scan:patterns\s*-->",
+                  text, flags=re.S)
+    if not m:
+        return []
+    pats = []
+    for line in m.group(1).splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        name, sep, rx = line.partition("|||")
+        if not sep:
+            name, rx = "ai pattern", name
+        try:
+            pats.append((name.strip(), re.compile(rx.strip(), re.I)))
+        except re.error:
+            pass
+    return pats
+
+
+def parse_config(text):
+    cfg = dict(FALLBACK["config"])
+    m = re.search(r"<!--\s*voice-config(.*?)-->", text, flags=re.S)
+    if m:
+        for line in m.group(1).splitlines():
+            if ":" in line:
+                k, v = line.split(":", 1)
+                k, v = k.strip().lower(), v.strip().lower()
+                if k == "max_exclamations":
+                    try:
+                        cfg[k] = int(v)
+                    except ValueError:
+                        pass
+                elif k in ("em_dash", "en_dash") and v in ("fail", "warn", "off"):
+                    cfg[k] = v
+    return cfg
+
+
+def load_rules(cli_path):
+    path = find_rules_file(cli_path)
+    if not path or not path.is_file():
+        print("note: voice.md not found; using minimal built-in fallback rules", file=sys.stderr)
+        return FALLBACK["banned"], FALLBACK["judgment"], [], dict(FALLBACK["config"]), None
+    text = path.read_text(encoding="utf-8", errors="replace")
+    banned = parse_block(text, "banned-phrases") or FALLBACK["banned"]
+    judgment = parse_block(text, "judgment-words")
+    patterns = parse_patterns(text)
+    return banned, judgment, patterns, parse_config(text), path
+
+
+def strip_to_copy(text, suffix):
+    """Remove non-copy regions so only reader-facing prose is scanned."""
+    if suffix in (".html", ".htm"):
+        text = re.sub(r"<script\b.*?</script>", " ", text, flags=re.S | re.I)
+        text = re.sub(r"<style\b.*?</style>", " ", text, flags=re.S | re.I)
+        text = re.sub(r"<!--.*?-->", " ", text, flags=re.S)
+        text = re.sub(r"<[^>]+>", " ", text)
+    if suffix == ".md":
+        text = re.sub(r"```.*?```", " ", text, flags=re.S)
+        text = re.sub(r"`[^`]*`", " ", text)
+        text = re.sub(r"<!--.*?-->", " ", text, flags=re.S)
+        text = re.sub(r"!\[[^\]]*\]\([^)]*\)", " ", text)  # markdown images / shields.io badges
+        text = re.sub(r"<[^>]+>", " ", text)               # inline HTML used for README layout
+    return text
+
+
+def word_hit(phrase, lowline):
+    return re.search(r"(?<![\w-])" + re.escape(phrase) + r"(?![\w-])", lowline)
+
+
+VERB_FIRST = re.compile(r"^[A-Z][a-z]{2,}(?:es|s)\b")  # Finds, Pulls, Structures, Runs, Gives
+
+
+def scan_structural(copy):
+    """Flag parallel-list uniformity that per-line regex cannot see: 3+ consecutive
+    short fragments that open with the same word-class (a present-tense verb), the
+    'Finds... / Pulls... / Structures...' cadence that reads as generated. Splits the
+    stripped copy on tag gaps (2+ spaces) and sentence ends so a prose list surfaces.
+    WARN-level, and honest about its limit: when a list is spread across separate DOM
+    elements with a label between each item, the opener is not the fragment's first
+    word and this misses it. That case is why the humanizer pass is a hard Gate 2
+    sub-check, not a suggestion."""
+    warns, frags = [], []
+    for i, line in enumerate(copy.splitlines(), 1):
+        for seg in re.split(r"\s{2,}|(?<=[.!?])\s+", line):
+            seg = seg.strip()
+            if seg:
+                frags.append((i, seg))
+    run = []
+
+    def flush(r):
+        if len(r) >= 3:
+            openers = ", ".join('"%s"' % s.split()[0] for _, s in r[:4])
+            warns.append((r[0][0],
+                          "parallel-list uniformity (%d fragments open with a present-tense verb: %s)"
+                          % (len(r), openers), r[0][1][:80]))
+
+    for ln, seg in frags:
+        if len(seg.split()) <= 9 and VERB_FIRST.match(seg):
+            run.append((ln, seg))
+        else:
+            flush(run)
+            run = []
+    flush(run)
+    return warns
+
+
+def scan_file(path, banned, judgment, patterns, cfg):
+    fails, warns = [], []
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    copy = strip_to_copy(raw, path.suffix.lower())
+    for i, line in enumerate(copy.splitlines(), 1):
+        low = line.lower()
+        ctx = line.strip()[:90]
+        for phrase in banned:
+            if word_hit(phrase, low):
+                fails.append((i, f"banned phrase: '{phrase}'", ctx))
+        for word in judgment:
+            if word_hit(word, low):
+                warns.append((i, f"judgment word (figurative use is banned): '{word}'", ctx))
+        for name, rx in patterns:
+            if rx.search(line):
+                warns.append((i, f"AI language pattern ({name})", ctx))
+        for dash, key, label in ((EM_DASH, "em_dash", "em dash in prose"),
+                                 (EN_DASH, "en_dash", "en dash in prose (use 'to' for ranges)")):
+            if dash in line and cfg.get(key) != "off":
+                (fails if cfg.get(key) == "fail" else warns).append((i, label, ctx))
+    warns += scan_structural(copy)
+    bangs = copy.count("!")
+    if bangs > cfg.get("max_exclamations", 1):
+        fails.append((0, f"{bangs} exclamation points (max {cfg.get('max_exclamations', 1)} per page)", ""))
+    return fails, warns
+
+
+def collect(targets):
+    for t in targets:
+        p = Path(t)
+        if p.is_dir():
+            for f in sorted(p.rglob("*")):
+                if f.suffix.lower() in EXTS:
+                    yield f
+        elif p.is_file():
+            yield p
+        else:
+            print(f"  ?  not found: {t}")
+
+
+def main(argv):
+    args = argv[1:]
+    rules_path = None
+    if "--rules" in args:
+        i = args.index("--rules")
+        try:
+            rules_path = args[i + 1]
+        except IndexError:
+            print("--rules requires a path", file=sys.stderr)
+            return 2
+        del args[i:i + 2]
+    if not args:
+        print(__doc__)
+        return 2
+    banned, judgment, patterns, cfg, src = load_rules(rules_path)
+    print(f"rules: {src if src else 'built-in fallback'} "
+          f"({len(banned)} banned, {len(judgment)} judgment, {len(patterns)} patterns)")
+    total_fail = 0
+    for f in collect(args):
+        fails, warns = scan_file(f, banned, judgment, patterns, cfg)
+        if not fails and not warns:
+            print(f"PASS  {f}")
+            continue
+        for line_no, why, ctx in fails:
+            loc = f"{f}:{line_no}" if line_no else f"{f}"
+            print(f"FAIL  {loc}  {why}" + (f"  | {ctx}" if ctx else ""))
+        for line_no, why, ctx in warns:
+            print(f"WARN  {f}:{line_no}  {why}" + (f"  | {ctx}" if ctx else ""))
+        total_fail += len(fails)
+    if total_fail:
+        print(f"\n{total_fail} violation(s). Restructure around concrete facts; do not synonym-swap.")
+        return 1
+    print("\nClean. Voice gate passed (review any WARN lines by hand).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))