page-foundry 2.9.1 → 3.2.0

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

@@ -175,6 +175,50 @@ def scan_structural(copy):
     return warns
 
 
+KICKER_PAIR = re.compile(
+    # A label element directly before a section heading. The body group refuses
+    # to cross its own closing tag or any block/heading boundary, so a long
+    # paragraph sitting before the real kicker cannot backtrack-swallow it.
+    r"<(p|span|div|small)\b([^>]*)>"
+    r"((?:[^<]|<(?!/\1\s*>|/?(?:p|div|small|h[1-6])\b)[^>]*>)*)"
+    r"</\1\s*>\s*<h([234])\b[^>]*>(.*?)</h\4\s*>",
+    re.S | re.I)
+
+
+def scan_html_kickers(raw):
+    """Repeated section kickers, absorbed from impeccable's detector (rule
+    repeated-section-kickers) under the v3.0 capability-ownership split: a short
+    uppercase label element sitting directly before an h2/h3/h4, three or more
+    times on a page, is AI editorial scaffolding. Impeccable gates on computed
+    font-size and letter-spacing; a static scanner cannot, so this gates on the
+    source-level tells instead: literal ALL-CAPS text, an `uppercase` utility
+    class or inline transform, or an eyebrow/kicker class name. Pairs split by
+    an intermediate wrapper element are invisible to this regex; the design
+    detect gate (impeccable detect, when installed) sees those with real styles.
+    WARN-level, threshold 3 per page, matching the source rule's advisory
+    severity and its 'once is fine; the pattern is the tell' doctrine."""
+    candidates = []
+    for m in KICKER_PAIR.finditer(raw):
+        attrs = m.group(2).lower()
+        kicker = re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", m.group(3))).strip()
+        heading = re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", m.group(5))).strip()
+        if not (2 <= len(kicker) <= 34) or len(heading) < 3:
+            continue
+        if re.match(r"step\s*\d+", kicker, re.I) or re.fullmatch(r"\d{1,2}", kicker):
+            continue
+        allcaps = re.search(r"[A-Z]", kicker) and not re.search(r"[a-z]", kicker)
+        styled = "uppercase" in attrs or "eyebrow" in attrs or "kicker" in attrs
+        if not (allcaps or styled):
+            continue
+        line_no = raw.count("\n", 0, m.start()) + 1
+        candidates.append((line_no, kicker, "h" + m.group(4), heading))
+    if len(candidates) < 3:
+        return []
+    return [(ln, "repeated section kickers ('%s' before %s, %d on page)"
+             % (kick, tag, len(candidates)), head[:80])
+            for ln, kick, tag, head in candidates]
+
+
 def scan_file(path, banned, judgment, patterns, cfg):
     fails, warns = [], []
     raw = path.read_text(encoding="utf-8", errors="replace")
@@ -196,6 +240,8 @@ def scan_file(path, banned, judgment, patterns, cfg):
             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)
+    if path.suffix.lower() in (".html", ".htm"):
+        warns += scan_html_kickers(raw)
     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)", ""))

package/skills/page-foundry/tests/build_fixture.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# Build calibration fixtures for run_audit.py. Idempotent.
+set -e
+ROOT="$1"; AUDIT="$2"
+rm -rf "$ROOT"; mkdir -p "$ROOT"/.agents "$ROOT"/pages/demo
+D="$ROOT/.agents/foundry/demo"
+mkdir -p "$D"/copy "$D"/tokens "$D"/comp
+
+cat > "$ROOT/.agents/product-marketing.md" <<'E'
+# Product Marketing Context
+**One-liner:** demo product for the solo builder shipping their own page.
+## Target Audience
+solo indie founders who ship many pages
+## Problems & Pain Points
+they ship a page and cannot tell why nobody signs up
+## Differentiation
+the spec is written before the design
+E
+
+cat > "$D/preflight.md" <<'E'
+## Preflight — 2026-07-24
+| companion | tier | state | resolved-via |
+|---|---|---|---|
+| product-marketing | core | present | npx skills list |
+| customer-research | core | present | npx skills list |
+| marketing-psychology | core | present | filesystem |
+| cro | core | present | filesystem |
+| copywriting | core | present | filesystem |
+| frontend-design | core | present | npx skills list |
+| humanizer | core | present | filesystem |
+| impeccable | core | present | npx impeccable |
+override: none
+E
+
+cat > "$D/voc.md" <<'E'
+# voc.md
+## Verbatim
+> I can't tell what this does.
+— Hacker News, https://news.ycombinator.com/item?id=42901780 · vunderba · 2025-02-01 · comprehension
+> after 10 days, I have zero signups. Not even one.
+— r/SaaS, https://www.reddit.com/r/SaaS/comments/1mf2dgx/ · SetDependent1293 · 2025-08-01 · no-signups
+> your landing page contains a lot of AI generated metaphors
+— Hacker News, https://news.ycombinator.com/item?id=46836627 · flexagoon · 2026-01-31 · slop
+## Themes
+1. comprehension failure (High, 3 sources)
+2. zero signups, no diagnosis (High)
+3. looks AI-made (Medium)
+E
+
+cat > "$D/persuasion-map.md" <<'E'
+# Persuasion map
+Levers chosen for a skeptical solo builder who reads before trusting.
+## Curse of Knowledge (primary lever)
+Lands on: the lead claim and the whole register. The buyer cannot read their own page cold.
+## Pratfall effect
+Lands on: the objection answers. Admit newness and slowness plainly.
+## Jobs to be Done
+Lands on: every capability line, framed as the outcome not the artifact.
+## Levers not chosen
+Social proof: out of scope, adoption is thin and stays TK.
+E
+
+cat > "$D/message-architecture.md" <<'E'
+# Message architecture
+Positioning: for the solo builder, demo is the thing that writes the spec, unlike a design tool that only renders what you hand it.
+## Hierarchy
+1. primary claim: the page argues a case
+2. secondary claim: the argument traces to a real quote
+3. tertiary claim: nothing is fabricated
+## Objection map
+O1: another AI builder. Answer: output is yours, no template.
+O2: I can just prompt an agent. Answer: the gates are the repeatability.
+O3: is it safe. Answer: one stdlib script, read it.
+## Proof inventory
+- real: the voice scanner, the run artifacts on disk
+- TK: adoption count
+E
+
+cat > "$D/page-spec.md" <<'E'
+# Page spec (oss-project)
+archetype: oss-project
+1. hero — primary claim — proof: the demo itself
+2. problem — the comprehension failure — no proof needed
+3. how it works — secondary claim — proof: the artifact chain
+4. objections — O1 O2 O3 — proof beside each
+5. install — CTA — the one command
+Answer block: the head title and meta description answer the query intent.
+Measurement plan: install count via the CLI, no third-party analytics.
+E
+
+cat > "$D/copy/hero-candidates.md" <<'E'
+# Hero candidates
+1. One brief in, a page that argues its case out. — score 8, message match high
+2. You already know what an AI page looks like. — score 9, specificity high
+3. The spec your page never got. — score 7, budget ok
+Pick: candidate 2.
+E
+
+cat > "$D/copy/approved-draft.md" <<'E'
+**`<title>`:** demo: the spec your page never got
+**meta description:** demo writes the marketing spec before anything gets designed.
+# Copy (page order)
+Hero: You already know what an AI page looks like.
+Problem: nobody can tell what it does.
+How: it writes the spec first, then builds from it.
+E
+
+cat > "$D/copy/copy-approved.md" <<'E'
+**`<title>`:** demo: the spec your page never got
+**meta description:** demo writes the marketing spec before anything gets designed.
+# Copy (frozen snapshot, page order)
+Hero: You already know what an AI page looks like.
+Problem: nobody can tell what it does.
+How: it writes the spec first, then builds from it.
+Install: one command.
+E
+
+cat > "$D/imagery-plan.md" <<'E'
+# Imagery plan
+Consistency rules: one grade (cool, high-contrast), 16:9 crops, hairline frames.
+- hero: real product screenshot, browser chrome cropped out, 16:9, cool grade.
+- proof: no image by choice; the gate report card carries the visual weight.
+- how-it-works: a diagram of the real component flow, on-token line weights.
+Every image traces to a slot here; no product screenshot is a mockup.
+E
+
+cat > "$D/states-motion.md" <<'E'
+# States and motion
+- form: error state = red hairline + aria-live message under the field; success =
+  inline confirmation, no redirect. loading = disabled button with a spinner glyph.
+- copy button: copied state swaps label to "Copied" for 1.4s.
+- focus: 2px ring, brand color, offset 2px, :focus-visible only.
+- hover: 120ms ease on transform/opacity only; nothing hover-only.
+- motion identity: one scroll-reveal on section entry, 200ms ease-out;
+  prefers-reduced-motion disables it and shows the static end state.
+E
+
+cat > "$D/tokens/plan-a.md" <<'E'
+# Plan A — instrument dark
+brand #ff3b1d on #0a0a0a, mono display, tight grid
+E
+cat > "$D/tokens/plan-b.md" <<'E'
+# Plan B — paper light
+brand #0a0a0a on #ffffff, serif display, wide grid
+E
+cat > "$D/tokens/selection.md" <<'E'
+Winner: plan-a. Why: the buyer reads at night in a terminal; instrument dark matches the register.
+E
+
+cat > "$D/comp/index.html" <<'E'
+<!doctype html><html><head><title>comp</title></head>
+<body><h1>You already know what an AI page looks like.</h1>
+<p>nobody can tell what it does.</p></body></html>
+E
+cat > "$D/comp/rounds.md" <<'E'
+Round 1: hero ran too tall at 1440, subhead lost. Fixed the scale.
+Round 2: 390 wrap held, density confirmed. Approved.
+E
+
+cat > "$ROOT/pages/demo/index.html" <<'E'
+<!doctype html><html><head><title>demo: the spec your page never got</title>
+<meta name="description" content="demo writes the marketing spec before anything gets designed."></head>
+<body><h1>You already know what an AI page looks like.</h1>
+<p>nobody can tell what it does. demo writes the spec first, then builds from it.</p></body></html>
+E
+cat > "$ROOT/pages/demo/theme.css" <<'E'
+:root{--brand:#ff3b1d;--bg:#0a0a0a}
+E
+cat > "$ROOT/pages/demo/llms.txt" <<'E'
+# demo
+The spec your page never got. Open source, MIT.
+E
+
+cat > "$ROOT/DESIGN.md" <<'E'
+---
+name: demo
+version: alpha
+---
+## Brand
+brand #ff3b1d on #0a0a0a; the signature is a hairline rule under the eyebrow.
+## Type
+display: mono, tight tracking; body: system sans, 1.6 line height.
+## Color
+--brand #ff3b1d; --bg #0a0a0a; --fg #f4f4f4; --muted #8a8a8a.
+## Layout
+container max 72ch; single column mobile, 12-col at 1024; 24px gutter.
+## Motion
+one scroll-reveal, 200ms ease-out; reduced-motion disables it.
+E
+
+cat > "$D/conversion-audit.md" <<'E'
+# Gate 1 conversion audit
+The heuristic scored twice: the builder self-score from full context, then the
+score of record from a fresh agent given only the page and the brief.
+Self score: 31. Independent score: 27. Divergence: 4 points, concentrated on the
+install CTA which is the strongest lever and currently thinnest.
+E
+
+cat > "$D/foundry-log.md" <<'E'
+# foundry-log.md: demo
+Per-property memory. Phase 6 appends after every run.
+
+### 2026-07-24 · build · oss-project
+- headline: You already know what an AI page looks like.
+- skeleton: hero, problem, how, objections, install · direct/static-hero/proof-adjacent/compressed
+- meclabs: C=27 (M4 V3 I2 F3 A2)
+- gates: all pass
+- companions: product-marketing, customer-research, marketing-psychology, cro, copywriting, frontend-design
+- degraded: none
+- open items: adoption count TK
+- conversion data: none exists yet
+- learnings: the cold re-score caught the CTA thinness
+E
+echo "fixture built at $ROOT"

package/skills/page-foundry/tests/run_audit_test.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Calibration regression for run_audit.py (issue #38).
+# Builds fixtures and asserts exit codes. No network, no deps.
+# Run from anywhere: bash skills/page-foundry/tests/run_audit_test.sh
+set -u
+HERE="$(cd "$(dirname "$0")" && pwd)"
+AUDIT="$HERE/../scripts/run_audit.py"
+BUILD="$HERE/build_fixture.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+fails=0
+
+assert_exit() {  # name expected dir extra...
+  local name="$1" expected="$2" dir="$3"; shift 3
+  python3 "$AUDIT" --mode build --archetype oss-project "$@" "$dir" >/dev/null 2>&1
+  local got=$?
+  if [ "$got" -eq "$expected" ]; then
+    echo "  ok   $name (exit $got)"
+  else
+    echo "  FAIL $name (got $got, want $expected)"; fails=$((fails+1))
+  fi
+}
+
+bash "$BUILD" "$TMP/clean" "$AUDIT" >/dev/null
+assert_exit "A: complete valid run passes" 0 "$TMP/clean/.agents/foundry/demo"
+
+cp -r "$TMP/clean" "$TMP/missing"
+rm "$TMP/missing/.agents/foundry/demo/message-architecture.md"
+assert_exit "B: missing required artifact fails" 1 "$TMP/missing/.agents/foundry/demo"
+
+cp -r "$TMP/clean" "$TMP/badlog"
+printf '# log\n\n## Run 1 (started 2026-07-24)\n- headline: x\n' > "$TMP/badlog/.agents/foundry/demo/foundry-log.md"
+assert_exit "C: foundry-log off documented format fails" 1 "$TMP/badlog/.agents/foundry/demo"
+
+cp -r "$TMP/clean" "$TMP/tk"
+sed -i.bak 's/one command\./[TK: the install command]/' "$TMP/tk/.agents/foundry/demo/copy/copy-approved.md" && rm -f "$TMP/tk/.agents/foundry/demo/copy/copy-approved.md.bak"
+assert_exit "D: unresolved [TK in copy fails" 1 "$TMP/tk/.agents/foundry/demo"
+
+cp -r "$TMP/clean" "$TMP/stale"; sleep 1; touch "$TMP/stale/pages/demo/index.html"
+assert_exit "E: mtime inversion is advisory (WARN), still passes" 0 "$TMP/stale/.agents/foundry/demo"
+
+# F: a core companion overridden at preflight may skip its artifact (honest PARTIAL).
+cp -r "$TMP/clean" "$TMP/override"
+D="$TMP/override/.agents/foundry/demo"
+rm "$D/persuasion-map.md"
+python3 - "$D/preflight.md" <<'PY'
+import sys
+p = sys.argv[1]; t = open(p).read()
+t = t.replace("| marketing-psychology | core | present | filesystem |",
+              "| marketing-psychology | core | missing | — |")
+t = t.replace("override: none", "override: marketing-psychology")
+open(p, "w").write(t)
+PY
+assert_exit "F: overridden companion may skip its artifact" 0 "$D"
+
+# G: a degraded claim naming a PRESENT, un-overridden companion fails.
+cp -r "$TMP/clean" "$TMP/lie"
+D="$TMP/lie/.agents/foundry/demo"
+python3 - "$D/foundry-log.md" <<'PY'
+import sys
+p = sys.argv[1]; t = open(p).read()
+open(p, "w").write(t.replace("- degraded: none",
+                             "- degraded: cro missing, ran on the reference file"))
+PY
+assert_exit "G: false degraded claim (companion was present) fails" 1 "$D"
+
+# H: a missing Phase 4 design output (imagery-plan/states-motion) fails.
+cp -r "$TMP/clean" "$TMP/noimg"
+rm "$TMP/noimg/.agents/foundry/demo/imagery-plan.md"
+assert_exit "H: missing imagery-plan.md fails" 1 "$TMP/noimg/.agents/foundry/demo"
+
+# I: impeccable is core — a missing DESIGN.md fails.
+cp -r "$TMP/clean" "$TMP/nodesign"
+rm "$TMP/nodesign/DESIGN.md"
+assert_exit "I: missing DESIGN.md (impeccable core) fails" 1 "$TMP/nodesign/.agents/foundry/demo"
+
+# J: impeccable overridden at preflight -> DESIGN.md may be absent (honest PARTIAL).
+cp -r "$TMP/clean" "$TMP/impoverride"
+rm "$TMP/impoverride/DESIGN.md"
+python3 - "$TMP/impoverride/.agents/foundry/demo/preflight.md" <<'PY'
+import sys
+p = sys.argv[1]; t = open(p).read()
+t = t.replace("| impeccable | core | present | npx impeccable |",
+              "| impeccable | core | missing | — |")
+t = t.replace("override: none", "override: impeccable")
+open(p, "w").write(t)
+PY
+assert_exit "J: impeccable overridden -> DESIGN.md absence is advisory" 0 "$TMP/impoverride/.agents/foundry/demo"
+
+echo ""
+if [ "$fails" -eq 0 ]; then echo "run_audit calibration: all fixtures pass"; else echo "run_audit calibration: $fails FAILED"; fi
+exit $fails