page-foundry 2.9.1 → 3.2.0

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

@@ -0,0 +1,1162 @@
+#!/usr/bin/env python3
+"""run_audit.py: mechanical orchestration gate for page-foundry.
+
+Audits a single run artifact directory and checks whether the documented
+artifact chain appears intact. This is a file-system audit only: it validates
+presence, basic structure, duplicate-content shortcuts, and mtime ordering.
+
+Usage:
+    python3 run_audit.py [flags] <run-dir>
+
+Flags:
+    --mode build|explore|handoff   required
+    --archetype NAME               required
+    --pages-dir PATH               optional; defaults to <workspace>/pages/<product>/
+    --handoff-dir PATH             optional; defaults to <workspace>/handoff/<product>/
+    --brief PATH                   optional; defaults to:
+                                   <workspace>/.agents/product-marketing.md
+                                   <workspace>/.claude/product-marketing.md
+                                   <run-dir>/product-marketing.md
+    --rewrite                      rewrite run; rewrite-diagnosis.md becomes required
+    --multipage                    multi-page run; site-context.md becomes required
+    --closing                      require a today-dated matching foundry-log entry
+    --tolerance SECONDS            mtime slack for staleness (default 2)
+    --impeccable-critique PATH     non-empty dir that satisfies the comp-record gate
+
+Exit code 0 = no HARD FAILs, 1 = HARD FAILs found, 2 = usage/environment error.
+"""
+
+import hashlib
+import os
+import re
+import sys
+from datetime import date, datetime
+from pathlib import Path
+
+MODES = {"build", "explore", "handoff"}
+PUBLIC_PRICING_ARCHETYPES = {
+    "pricing-page",
+    "saas-homepage",
+    "course-sales",
+    "membership-community",
+    "docs-dev-tool-landing",
+}
+FORM_CENTRIC_ARCHETYPES = {
+    "newsletter-capture",
+    "waitlist-coming-soon",
+    "event-webinar",
+    "campaign-landing",
+}
+OTHER_ARCHETYPES = {
+    "oss-project",
+    "mobile-app",
+    "personal-home",
+    "comparison-alternatives",
+    "agency-services",
+    "ecommerce-product",
+    "changelog-launch-post",
+    "thank-you-post-conversion",
+}
+KNOWN_ARCHETYPES = PUBLIC_PRICING_ARCHETYPES | FORM_CENTRIC_ARCHETYPES | OTHER_ARCHETYPES
+REJECT_SOURCE_FIELDS = {
+    "customer interviews",
+    "interviews",
+    "reviews",
+    "g2",
+    "capterra",
+    "users",
+    "customers",
+    "reddit",
+    "forums",
+    "the internet",
+    "various",
+    "misc",
+    "survey",
+}
+REQUIRED_FILES = (
+    ("brief", "brief", 3),
+    ("run", "voc.md", 5),
+    ("run", "message-architecture.md", 6),
+    ("run", "persuasion-map.md", 4),
+    ("run", "page-spec.md", 6),
+    ("run", "copy/hero-candidates.md", 2),
+    ("run", "copy/approved-draft.md", 4),
+    ("run", "copy/copy-approved.md", 4),
+    ("run", "conversion-audit.md", 4),
+)
+HANDOFF_FILES = (
+    "00-master-prompt.md",
+    "01-copy.md",
+    "02-page-spec.md",
+    "03-design-direction.md",
+    "04-acceptance-criteria.md",
+    "05-voice-rules.md",
+    "06-return-spec.md",
+    "DESIGN.md",
+)
+LOG_FIELDS = (
+    "headline",
+    "skeleton",
+    "meclabs",
+    "gates",
+    "companions",
+    "degraded",
+    "open items",
+    "conversion data",
+    "learnings",
+)
+# Which companion owns each required artifact. Used with preflight.md to tell a
+# legitimately-overridden companion (artifact absence is expected) from one that
+# was present but skipped (artifact absence is a FAIL). Artifacts with no entry
+# are page-foundry's own synthesis and are always required.
+CORE_ARTIFACT_COMPANION = {
+    "brief": "product-marketing",
+    "voc.md": "customer-research",
+    "persuasion-map.md": "marketing-psychology",
+    "conversion-audit.md": "cro",
+    "copy/hero-candidates.md": "copywriting",
+    # frontend-design (theme.css) and humanizer (voice pass) are core too but
+    # their outputs are checked elsewhere; impeccable's DESIGN.md is handled by a
+    # dedicated workspace-root check in audit_run (it is not run-dir-relative).
+}
+POINTER_RE = re.compile(
+    r"(https?://|[A-Za-z0-9_./-]+:\d+|#[A-Za-z][\w:-]*|\b(?:PR|MR|GH-|JIRA-|PF-|BUG-|ISSUE-|TASK-|TICKET-)?[A-Z]+-\d+\b|\b[a-f0-9]{7,40}\b)",
+    re.I,
+)
+COMMENT_RE = re.compile(r"^\s*(#|//|<!--)")
+NUMBERED_LINE_RE = re.compile(r"^\s*\d+\.\s+")
+
+
+def usage_error(message):
+    print(message, file=sys.stderr)
+    print(__doc__, file=sys.stderr)
+    return 2
+
+
+def read_text(path):
+    try:
+        return Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return exc
+
+
+def stat_path(path):
+    try:
+        return Path(path).stat()
+    except OSError as exc:
+        return exc
+
+
+def iso_mtime(path):
+    st = stat_path(path)
+    if isinstance(st, OSError):
+        return str(st)
+    return datetime.fromtimestamp(st.st_mtime).isoformat(timespec="seconds")
+
+
+def data_lines(text):
+    lines = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or COMMENT_RE.match(line):
+            continue
+        if line.startswith("#"):
+            continue
+        lines.append(line)
+    return lines
+
+
+def emit(results, status, subject, why=None, ctx=None):
+    line = status + "  " + str(subject)
+    if why:
+        line += "  " + why
+    if ctx:
+        line += "  | " + ctx
+    results.append((status, line))
+
+
+def resolve_workspace(run_dir):
+    run_dir = Path(run_dir).resolve()
+    for parent in (run_dir,) + tuple(run_dir.parents):
+        if (parent / ".agents").is_dir():
+            return parent
+    return None
+
+
+def resolve_brief(args, workspace, run_dir):
+    if args["brief"]:
+        return Path(args["brief"]), False
+    candidates = []
+    if workspace:
+        candidates.append(workspace / ".agents" / "product-marketing.md")
+        candidates.append(workspace / ".claude" / "product-marketing.md")
+    candidates.append(run_dir / "product-marketing.md")
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate, False
+    return candidates[0] if candidates else run_dir / "product-marketing.md", True
+
+
+def resolve_related_dir(args_value, workspace, product, folder_name):
+    if args_value:
+        return Path(args_value), False
+    if workspace:
+        return workspace / folder_name / product, True
+    return Path(folder_name) / product, True
+
+
+def count_nonblank_files(path):
+    count = 0
+    for item in sorted(Path(path).rglob("*")):
+        if item.is_file():
+            st = stat_path(item)
+            if not isinstance(st, OSError) and st.st_size > 0:
+                count += 1
+    return count
+
+
+def newest_file(path):
+    newest = None
+    newest_mtime = None
+    for item in sorted(Path(path).rglob("*")):
+        if not item.is_file():
+            continue
+        st = stat_path(item)
+        if isinstance(st, OSError):
+            continue
+        if newest is None or st.st_mtime > newest_mtime or (st.st_mtime == newest_mtime and str(item) < str(newest)):
+            newest = item
+            newest_mtime = st.st_mtime
+    return newest
+
+
+def sha256_file(path):
+    try:
+        h = hashlib.sha256()
+        with open(path, "rb") as handle:
+            while True:
+                chunk = handle.read(65536)
+                if not chunk:
+                    break
+                h.update(chunk)
+        return h.hexdigest()
+    except OSError as exc:
+        return exc
+
+
+def normalize_text(text):
+    return "\n".join(line.strip() for line in text.splitlines() if line.strip())
+
+
+def has_form_design(text):
+    lines = text.splitlines()
+    has_label = False
+    has_fields = False
+    for index, raw in enumerate(lines):
+        line = raw.strip()
+        if not line:
+            continue
+        if re.search(r"\bform\b", line, re.I) and (line.startswith("#") or ":" in line or re.search(r"\bform design\b", line, re.I)):
+            has_label = True
+            for follow in lines[index + 1:index + 8]:
+                probe = follow.strip()
+                if not probe:
+                    continue
+                if re.search(r"\b(field|fields|name|email|phone|company|message|submit|cta)\b", probe, re.I):
+                    has_fields = True
+                    break
+        if has_label and has_fields:
+            return True
+    return False
+
+
+def line_has_pointer(field):
+    field = field.strip()
+    return bool(POINTER_RE.search(field))
+
+
+def parse_preflight(text):
+    # Reads the preflight.md table written at Phase -1 (SKILL.md step 1). Returns
+    # {companion: state} and the set of core companions the user overrode. A
+    # companion is "available" when its state is present/outdated (outdated still
+    # runs as primary) and it is not on the override line; only then is its
+    # OUTPUT artifact mandatory.
+    states = {}
+    override = set()
+    for raw in text.splitlines():
+        line = raw.strip()
+        m = re.match(r"^\|\s*([A-Za-z0-9_-]+)\s*\|\s*(core|enhancer)\s*\|\s*([A-Za-z-]+)\s*\|", line)
+        if m and m.group(1).lower() not in ("companion",):
+            states[m.group(1).lower()] = m.group(3).lower()
+        o = re.match(r"^override:\s*(.+)$", line, re.I)
+        if o:
+            val = o.group(1).strip()
+            if val.lower() not in ("none", "-", ""):
+                for name in re.split(r"[,\s]+", val):
+                    if name.strip():
+                        override.add(name.strip().lower())
+    return states, override
+
+
+def companion_available(states, override, companion):
+    # No preflight record -> treat as available (strict: artifact required). A
+    # recorded state of present/outdated and not overridden -> available.
+    if companion in override:
+        return False
+    state = states.get(companion)
+    if state is None:
+        return True
+    return state in ("present", "outdated")
+
+
+def parse_voc(text):
+    problems = []
+    lines = text.splitlines()
+    has_verbatim = any(re.match(r"^\s*##\s+Verbatim\b", line, re.I) for line in lines)
+    has_themes = any(re.match(r"^\s*##\s+Themes\b", line, re.I) for line in lines)
+    if not has_verbatim:
+        problems.append(("missing ## Verbatim section", None))
+    if not has_themes:
+        problems.append(("missing ## Themes section", None))
+    quote_count = 0
+    for index, raw in enumerate(lines):
+        if not raw.lstrip().startswith(">"):
+            continue
+        quote_count += 1
+        ctx = raw.strip()[:120]
+        found_attr = None
+        for probe in lines[index + 1:]:
+            stripped = probe.strip()
+            if not stripped:
+                continue
+            if stripped.startswith(">"):
+                break
+            if stripped.startswith("—") or stripped.startswith("-"):
+                found_attr = stripped.lstrip("—-").strip()
+                break
+            if stripped.startswith("#"):
+                break
+            break
+        if not found_attr:
+            problems.append(("quote missing attribution within next non-blank line", ctx))
+            continue
+        fields = [part.strip() for part in found_attr.split("·") if part.strip()]
+        if len(fields) < 2:
+            problems.append(("quote attribution needs at least two ·-separated fields", ctx))
+            continue
+        first = fields[0].lower()
+        if first in REJECT_SOURCE_FIELDS:
+            problems.append(("quote attribution uses a genre, not a real source pointer", ctx))
+            continue
+        if not line_has_pointer(fields[0]):
+            problems.append(("quote attribution first field is not a real pointer", ctx))
+    if quote_count < 1:
+        problems.append(("missing quote lines in ## Verbatim", None))
+    ranked = 0
+    for raw in lines:
+        if NUMBERED_LINE_RE.match(raw) and re.search(r"\b(High|Medium|Low)\b", raw):
+            ranked += 1
+    if ranked < 1:
+        problems.append(("## Themes needs at least one ranked entry with High/Medium/Low confidence", None))
+    return problems
+
+
+def parse_message_architecture(text):
+    lines = text.splitlines()
+    has_unlike = any("unlike" in line.lower() for line in lines)
+    hierarchy_count = sum(1 for line in lines if re.search(r"\b(claim|tier|hierarchy|primary|secondary|tertiary)\b", line, re.I))
+    objections = 0
+    in_objections = False
+    has_proof = False
+    for raw in lines:
+        line = raw.strip()
+        if re.search(r"\bobjection", line, re.I):
+            in_objections = True
+            continue
+        if in_objections and (line.startswith("#") or re.search(r"\bproof\b", line, re.I)):
+            in_objections = False
+        if in_objections and line and not line.startswith("#"):
+            objections += 1
+        if re.search(r"\bproof\b", line, re.I):
+            has_proof = True
+    problems = []
+    if not has_unlike:
+        problems.append("missing positioning line with 'unlike'")
+    if hierarchy_count < 3:
+        problems.append("needs at least three hierarchy claim lines")
+    if objections < 3:
+        problems.append("objection section needs at least three entries")
+    if not has_proof:
+        problems.append("missing proof-inventory section")
+    return problems
+
+
+def parse_persuasion_map(text):
+    # Structure floor, not a semantic judge: the documented contract
+    # (ship-gates.md:268 — "persuasion-map.md written, levers applied and where")
+    # is that the map names multiple levers AND says where each acts. Count the
+    # two signals independently and require a floor of each. The earlier version
+    # counted a "lever" for any block mentioning the word — intro prose, section
+    # headers — then demanded landing >= that inflated count, which the v3.0
+    # dogfood failed despite placing every lever with "Lands on:".
+    lever_headers = len(re.findall(r"^\s*#{2,4}\s+.*\blever", text, re.I | re.M))
+    if lever_headers < 2:
+        # Levers titled by name ("### Pratfall effect") rather than with the
+        # word "lever": fall back to counting third/fourth-level headers.
+        lever_headers = len(re.findall(r"^\s*#{3,4}\s+\S", text, re.M))
+    landing = len(re.findall(r"\b(lands? on|where it lands|claim order|placement)\b", text, re.I))
+    problems = []
+    if lever_headers < 2:
+        problems.append("needs at least two named lever entries")
+    if landing < 2:
+        problems.append("levers need a where-it-lands pointer (found %d)" % landing)
+    return problems
+
+
+def parse_page_spec(text, archetype):
+    problems = []
+    if archetype.lower() not in text.lower():
+        problems.append("missing declared archetype string")
+    numbered = sum(1 for line in text.splitlines() if NUMBERED_LINE_RE.match(line))
+    if numbered < 3:
+        problems.append("needs at least three numbered sections")
+    if not re.search(r"\banswer block\b", text, re.I):
+        problems.append("missing answer block entry")
+    if not re.search(r"\bmeasurement plan\b", text, re.I):
+        problems.append("missing measurement-plan entry")
+    return problems
+
+
+def parse_copy_approved(text):
+    problems = []
+    # The label may carry markdown emphasis and backticks: the documented form
+    # is a labeled entry, and a real snapshot writes it as **`<title>`:**. Allow
+    # leading *, _, `, >, and list bullets before the label. (Matching only a
+    # bare line-start "title:" was miscalibration against the v3.0 dogfood.)
+    label_prefix = r"^[\s>*_`-]*"
+    if not re.search(label_prefix + r"(?:<title>|title)`?\s*:", text, re.I | re.M):
+        problems.append("missing labeled <title> entry")
+    if not re.search(label_prefix + r"meta[- ]description`?\s*:", text, re.I | re.M):
+        problems.append("missing meta-description entry")
+    if "[TK" in text:
+        problems.append("contains unresolved [TK placeholder")
+    return problems
+
+
+def extract_snapshot_title(text):
+    for raw in text.splitlines():
+        # Same markdown-tolerant label as parse_copy_approved; strip trailing
+        # emphasis/backticks off the captured value.
+        m = re.match(r"^[\s>*_`-]*(?:<title>|title)`?\s*:\s*(.+?)\s*$", raw, re.I)
+        if m:
+            return m.group(1).strip().strip("*_`").strip()
+    return None
+
+
+def parse_index_html(text, snapshot_title):
+    problems = []
+    title_match = re.search(r"<title>(.*?)</title>", text, re.I | re.S)
+    if not title_match:
+        problems.append("missing <title> tag")
+    else:
+        actual_title = re.sub(r"\s+", " ", title_match.group(1)).strip()
+        if snapshot_title and snapshot_title not in actual_title:
+            problems.append("title mismatch")
+    if "[TK" in text:
+        problems.append("contains unresolved [TK placeholder")
+    h1_count = len(re.findall(r"<h1\b", text, re.I))
+    if h1_count != 1:
+        problems.append("must contain exactly one <h1>")
+    return problems, title_match.group(1).strip() if title_match else None
+
+
+def parse_conversion_audit(text):
+    # This file's documented contract is at ship-gates.md:17 — it "records both
+    # scores and the divergence." That is the HARD requirement here. The compact
+    # `C={n} (M{n} V{n} I{n} F{n} A{n})` breakdown is documented for the
+    # foundry-log (SKILL.md:354), and parse_foundry_log enforces it THERE; a
+    # per-factor breakdown is not part of this file's spec, so its absence is a
+    # WARN, not a FAIL. Requiring an undocumented format was the miscalibration
+    # that failed the v3.0 dogfood audit (which scored in a table, not the
+    # compact line).
+    problems = []
+    warns = []
+    # Two scores: accept the compact `C=<n>` form OR two plain "score" numbers
+    # (the dogfood wrote "Self score: 31. Independent score: 28.").
+    c_matches = re.findall(r"\bC\s*=\s*-?\d+\b", text)
+    score_matches = re.findall(r"\bscores?\b[^\n]*?-?\d+", text, re.I)
+    has_two_scores = len(c_matches) >= 2 or len(score_matches) >= 2
+    has_divergence = re.search(r"\bdivergence\b", text, re.I) is not None
+    if not (has_two_scores or has_divergence):
+        if re.search(r"\bno fresh context was available\b", text, re.I):
+            warns.append("records no fresh context was available instead of a second score")
+        else:
+            problems.append("missing both scores and the divergence note (ship-gates.md:17)")
+    missing_factors = [f for f in ("M", "V", "I", "F", "A")
+                       if not re.search(r"\b" + f + r"\s*=\s*-?\d+\b", text)]
+    if missing_factors:
+        warns.append("no compact factor breakdown (%s); documented for the log, not this file"
+                     % ",".join(missing_factors))
+    return problems, warns
+
+
+def parse_log_entries(text):
+    entries = []
+    current = None
+    for raw in text.splitlines():
+        head = re.match(r"^\s*###\s+(\d{4}-\d{2}-\d{2})\s+·\s+(\S+)\s+·\s+(.+?)\s*$", raw)
+        if head:
+            if current:
+                entries.append(current)
+            current = {
+                "date": head.group(1),
+                "mode": head.group(2),
+                "archetype": head.group(3).strip(),
+                "fields": {},
+            }
+            continue
+        if current is None:
+            continue
+        # Documented format writes each field as a bullet: "- headline: {shipped H1}".
+        field = re.match(r"^\s*[-*]?\s*([A-Za-z ]+):\s*(.*?)\s*$", raw)
+        if field:
+            current["fields"][field.group(1).strip().lower()] = field.group(2)
+    if current:
+        entries.append(current)
+    return entries
+
+
+def parse_foundry_log(text):
+    problems = []
+    entries = parse_log_entries(text)
+    if not entries:
+        problems.append(("foundry-log.md", "missing parseable ### YYYY-MM-DD · mode · archetype entries", None))
+        return entries, problems
+    for entry in entries:
+        missing = [field for field in LOG_FIELDS if field not in entry["fields"]]
+        if missing:
+            problems.append(
+                (
+                    "foundry-log.md:%s" % entry["date"],
+                    "entry missing required fields",
+                    ", ".join(missing),
+                )
+            )
+        skeleton = entry["fields"].get("skeleton", "")
+        if len([part.strip() for part in skeleton.split("/") if part.strip()]) != 4:
+            problems.append(
+                (
+                    "foundry-log.md:%s" % entry["date"],
+                    "skeleton must carry four /-separated axis settings",
+                    skeleton,
+                )
+            )
+        meclabs = entry["fields"].get("meclabs", "")
+        if not re.search(r"\bC\s*=\s*-?\d+\b", meclabs):
+            problems.append(
+                (
+                    "foundry-log.md:%s" % entry["date"],
+                    "meclabs line must parse numerically",
+                    meclabs,
+                )
+            )
+    return entries, problems
+
+
+def require_file(results, path, label, floor):
+    st = stat_path(path)
+    if isinstance(st, OSError):
+        emit(results, "FAIL", path, "%s unreadable or missing" % label, str(st))
+        return None
+    if not Path(path).is_file():
+        emit(results, "FAIL", path, "%s is not a file" % label)
+        return None
+    if st.st_size <= 0:
+        emit(results, "FAIL", path, "%s is empty" % label)
+        return None
+    text = read_text(path)
+    if isinstance(text, OSError):
+        emit(results, "FAIL", path, "%s unreadable" % label, str(text))
+        return None
+    lines = data_lines(text)
+    if len(lines) < floor:
+        emit(results, "FAIL", path, "%s is too thin (%d < %d data lines)" % (label, len(lines), floor))
+        return None
+    emit(results, "PASS", path)
+    return {"path": Path(path), "text": text, "lines": lines}
+
+
+def require_dir(results, path, label, minimum_files):
+    st = stat_path(path)
+    if isinstance(st, OSError):
+        emit(results, "FAIL", path, "%s unreadable or missing" % label, str(st))
+        return None
+    if not Path(path).is_dir():
+        emit(results, "FAIL", path, "%s is not a directory" % label)
+        return None
+    count = count_nonblank_files(path)
+    if count < minimum_files:
+        emit(results, "FAIL", path, "%s needs at least %d non-empty file(s)" % (label, minimum_files))
+        return None
+    emit(results, "PASS", path)
+    return {"path": Path(path), "count": count}
+
+
+def require_comp_record(results, run_dir, critique_dir):
+    if critique_dir:
+        info = require_dir(results, critique_dir, "impeccable critique dir", 1)
+        return info["path"] if info else None
+    record = run_dir / "comp" / "rounds.md"
+    info = require_file(results, record, "comp record", 2)
+    return info["path"] if info else None
+
+
+def optional_file(results, path, label, floor):
+    st = stat_path(path)
+    if isinstance(st, OSError):
+        emit(results, "WARN", path, "%s missing" % label)
+        return None
+    if not Path(path).is_file():
+        emit(results, "WARN", path, "%s is not a file" % label)
+        return None
+    text = read_text(path)
+    if isinstance(text, OSError):
+        emit(results, "WARN", path, "%s unreadable" % label, str(text))
+        return None
+    if len(data_lines(text)) < floor:
+        emit(results, "WARN", path, "%s is thin" % label)
+        return None
+    emit(results, "PASS", path)
+    return {"path": Path(path), "text": text}
+
+
+def skip(results, subject, why):
+    emit(results, "SKIP", subject, why)
+
+
+def is_projection_pair(first, second, package_dir):
+    """True when exactly one of the two paths lives inside the handoff package.
+
+    The package is a documented projection of the run directory (01-copy.md IS
+    copy/copy-approved.md, 02-page-spec.md IS the spec), so identical content
+    across that boundary is the contract being honored, not a chain shortcut.
+    Duplicate detection stays in force on both sides of the boundary.
+    """
+    if not package_dir:
+        return False
+    root = str(Path(package_dir).resolve())
+    inside_first = str(Path(first).resolve()).startswith(root + os.sep)
+    inside_second = str(Path(second).resolve()).startswith(root + os.sep)
+    return inside_first != inside_second
+
+
+def check_duplicate_hashes(results, infos, package_dir):
+    seen = {}
+    failures = 0
+    for info in infos:
+        digest = sha256_file(info["path"])
+        if isinstance(digest, OSError):
+            emit(results, "FAIL", info["path"], "could not hash artifact", str(digest))
+            failures += 1
+            continue
+        path_str = str(info["path"])
+        twin = seen.get(digest)
+        if twin and not is_projection_pair(path_str, twin, package_dir):
+            emit(results, "FAIL", path_str, "duplicate content hash matches distinct required artifact", twin)
+            failures += 1
+        else:
+            seen[digest] = path_str
+    return failures
+
+
+def check_stale(results, target, source, tolerance):
+    if not Path(target).exists() or not Path(source).exists():
+        return 0
+    target_stat = stat_path(target)
+    source_stat = stat_path(source)
+    if isinstance(target_stat, OSError) or isinstance(source_stat, OSError):
+        return 0
+    gap = source_stat.st_mtime - target_stat.st_mtime
+    if gap > tolerance:
+        # WARN, never FAIL. An mtime inversion has two innocent causes that are
+        # indistinguishable from a genuinely stale derivation: the source was
+        # legitimately edited AFTER the derived artifact (a provenance note
+        # appended to voc.md, a late brief correction), or mtimes were reordered
+        # by a copy/checkout. mtime cannot answer "was this derived from THIS
+        # version of the source", so it must not block a ship. It is surfaced for
+        # a human to read: an inversion is worth a look (it did catch a real
+        # not-re-scored conversion audit in the v3.0 dogfood), it just is not
+        # proof. See the limits block at the foot of this file.
+        emit(
+            results,
+            "WARN",
+            "%s <- %s" % (target, source),
+            "derived artifact older than source by %.1fs (mtime ordering only; review by hand)" % gap,
+            "target=%s source=%s" % (
+                datetime.fromtimestamp(target_stat.st_mtime).isoformat(timespec="seconds"),
+                datetime.fromtimestamp(source_stat.st_mtime).isoformat(timespec="seconds"),
+            ),
+        )
+        return 0
+    emit(results, "PASS", "%s <- %s" % (target, source))
+    return 0
+
+
+def build_arg_state(argv):
+    args = {
+        "mode": None,
+        "archetype": None,
+        "pages_dir": None,
+        "handoff_dir": None,
+        "brief": None,
+        "rewrite": False,
+        "multipage": False,
+        "closing": False,
+        "tolerance": 2,
+        "impeccable_critique": None,
+        "run_dir": None,
+    }
+    flags_with_values = {
+        "--mode": "mode",
+        "--archetype": "archetype",
+        "--pages-dir": "pages_dir",
+        "--handoff-dir": "handoff_dir",
+        "--brief": "brief",
+        "--tolerance": "tolerance",
+        "--impeccable-critique": "impeccable_critique",
+    }
+    bool_flags = {"--rewrite": "rewrite", "--multipage": "multipage", "--closing": "closing"}
+    items = list(argv[1:])
+    if not items:
+        print(__doc__)
+        return None
+    index = 0
+    positionals = []
+    while index < len(items):
+        item = items[index]
+        if item in flags_with_values:
+            if index + 1 >= len(items) or items[index + 1].startswith("--"):
+                return usage_error("%s requires a value" % item)
+            args[flags_with_values[item]] = items[index + 1]
+            index += 2
+            continue
+        if item in bool_flags:
+            args[bool_flags[item]] = True
+            index += 1
+            continue
+        if item.startswith("--"):
+            return usage_error("unknown flag: %s" % item)
+        positionals.append(item)
+        index += 1
+    if len(positionals) != 1:
+        return usage_error("expected exactly one <run-dir> positional argument")
+    args["run_dir"] = Path(positionals[0])
+    if args["mode"] not in MODES:
+        return usage_error("--mode must be one of build, explore, handoff")
+    if not args["archetype"]:
+        return usage_error("--archetype is required")
+    try:
+        args["tolerance"] = int(args["tolerance"])
+    except (TypeError, ValueError):
+        return usage_error("--tolerance must be an integer number of seconds")
+    if args["tolerance"] < 0:
+        return usage_error("--tolerance must be >= 0")
+    if not args["run_dir"].is_dir():
+        return usage_error("run directory does not exist: %s" % args["run_dir"])
+    return args
+
+
+def audit_run(args):
+    results = []
+    run_dir = args["run_dir"].resolve()
+    workspace = resolve_workspace(run_dir)
+    product = run_dir.name
+    brief_path, brief_defaulted = resolve_brief(args, workspace, run_dir)
+    pages_dir, pages_defaulted = resolve_related_dir(args["pages_dir"], workspace, product, "pages")
+    handoff_dir, handoff_defaulted = resolve_related_dir(args["handoff_dir"], workspace, product, "handoff")
+    critique_dir = Path(args["impeccable_critique"]) if args["impeccable_critique"] else None
+    token_dir = run_dir / "tokens"
+    token_count = count_nonblank_files(token_dir) if token_dir.is_dir() else 0
+    print(
+        "run: %s  mode=%s  archetype=%s  tokens=%d  pages=%s%s  handoff=%s%s  brief=%s%s"
+        % (
+            run_dir,
+            args["mode"],
+            args["archetype"],
+            token_count,
+            pages_dir,
+            " [default]" if pages_defaulted else "",
+            handoff_dir,
+            " [default]" if handoff_defaulted else "",
+            brief_path,
+            " [default]" if brief_defaulted else "",
+        )
+    )
+
+    # Preflight record: what was actually available this run. Absent -> strict
+    # (every core artifact required); present -> a core companion the user
+    # overrode has its artifact demoted to advisory. This is what lets an
+    # honestly-declared PARTIAL run pass while a present-but-skipped companion
+    # still fails on its missing artifact.
+    preflight_path = run_dir / "preflight.md"
+    if preflight_path.is_file():
+        pf_text = read_text(preflight_path)
+        pf_states, pf_override = parse_preflight(pf_text) if isinstance(pf_text, str) else ({}, set())
+        emit(results, "PASS", preflight_path, "preflight recorded (%d companions, override: %s)"
+             % (len(pf_states), ", ".join(sorted(pf_override)) or "none"))
+    else:
+        pf_states, pf_override = {}, set()
+        emit(results, "WARN", preflight_path,
+             "preflight.md missing; degraded-claim cross-check unavailable, core artifacts held strict (SKILL.md Phase -1)")
+
+    required_infos = []
+    brief_info = require_file(results, brief_path, "brief", 3)
+    if brief_info:
+        required_infos.append(brief_info)
+    for origin, rel, floor in REQUIRED_FILES[1:]:
+        path = run_dir / rel
+        companion = CORE_ARTIFACT_COMPANION.get(rel)
+        if companion and not companion_available(pf_states, pf_override, companion):
+            # Companion overridden/declined at preflight: its artifact is expected
+            # to be absent. Advisory only, so an honest PARTIAL run is not failed.
+            optional_file(results, path, "%s (%s declined at preflight)" % (rel, companion), floor)
+            continue
+        info = require_file(results, path, rel, floor)
+        if info:
+            required_infos.append(info)
+
+    tokens_info = require_dir(results, token_dir, "tokens dir", 1)
+    if tokens_info:
+        newest_token = newest_file(token_dir)
+        if args["mode"] == "explore":
+            if tokens_info["count"] < 2:
+                emit(results, "FAIL", token_dir, "explore mode needs at least two token files")
+            elif tokens_info["count"] == 2:
+                emit(results, "WARN", token_dir, "explore mode has only two token files; documented default is >=3")
+        required_infos.extend({"path": item} for item in sorted(token_dir.rglob("*")) if item.is_file())
+    else:
+        newest_token = None
+
+    if args["rewrite"]:
+        rewrite_info = require_file(results, run_dir / "rewrite-diagnosis.md", "rewrite-diagnosis.md", 3)
+        if rewrite_info:
+            required_infos.append(rewrite_info)
+    else:
+        optional_file(results, run_dir / "rewrite-diagnosis.md", "rewrite-diagnosis.md", 3)
+
+    if args["multipage"]:
+        site_context_info = require_file(results, run_dir / "site-context.md", "site-context.md", 3)
+        if site_context_info:
+            required_infos.append(site_context_info)
+    else:
+        site_context_info = optional_file(results, run_dir / "site-context.md", "site-context.md", 3)
+
+    optional_file(results, run_dir / "experiments.md", "experiments.md", 2)
+
+    known_archetype = args["archetype"] in KNOWN_ARCHETYPES
+    if not known_archetype:
+        emit(results, "WARN", args["archetype"], "unknown archetype string; conditional checks skipped")
+
+    if args["mode"] in ("build", "explore", "handoff"):
+        # Phase 4 design outputs: imagery and interactive-state plans. Required in
+        # every mode because the design decisions they record must be made even
+        # when an external tool does the building (handoff carries them in the
+        # package). A page that skips them defaults to a text wall and browser
+        # states, the two strongest remaining AI tells.
+        img_info = require_file(results, run_dir / "imagery-plan.md", "imagery-plan.md", 3)
+        if img_info:
+            required_infos.append(img_info)
+        sm_info = require_file(results, run_dir / "states-motion.md", "states-motion.md", 3)
+        if sm_info:
+            required_infos.append(sm_info)
+
+    # DESIGN.md: impeccable's design-system artifact (Phase 4 step 8), impeccable
+    # being a CORE companion. In build/explore it lives at the product repo root
+    # (workspace) or the run dir; in handoff it is the package projection, checked
+    # via HANDOFF_FILES. Required unless impeccable was overridden at preflight,
+    # in which case its absence is advisory (an honest PARTIAL run).
+    if args["mode"] in ("build", "explore"):
+        design_candidates = [workspace / "DESIGN.md", run_dir / "DESIGN.md"]
+        design_path = next((p for p in design_candidates if p.is_file()), design_candidates[0])
+        if companion_available(pf_states, pf_override, "impeccable"):
+            d_info = require_file(results, design_path, "DESIGN.md (impeccable, core)", 5)
+            if d_info:
+                required_infos.append(d_info)
+        else:
+            optional_file(results, design_path, "DESIGN.md (impeccable declined at preflight)", 5)
+
+    if args["mode"] in ("build", "explore"):
+        comp_info = require_file(results, run_dir / "comp" / "index.html", "comp/index.html", 3)
+        if comp_info:
+            required_infos.append(comp_info)
+        comp_record = require_comp_record(results, run_dir, critique_dir)
+        page_index_info = require_file(results, pages_dir / "index.html", "pages index", 3)
+        if page_index_info:
+            required_infos.append(page_index_info)
+        theme_info = require_file(results, pages_dir / "theme.css", "theme.css", 1)
+        if theme_info:
+            required_infos.append(theme_info)
+        llms_info = require_file(results, pages_dir / "llms.txt", "llms.txt", 1)
+        if llms_info:
+            required_infos.append(llms_info)
+        optional_file(results, run_dir / "og.html", "og.html", 1)
+        assets_dir = pages_dir / "assets"
+        og_found = False
+        if assets_dir.is_dir():
+            for candidate in sorted(assets_dir.rglob("*")):
+                if candidate.is_file() and re.search(r"\b(?:og|open-graph)\b", candidate.name, re.I):
+                    og_found = True
+                    break
+        if og_found:
+            emit(results, "PASS", assets_dir)
+        else:
+            emit(results, "WARN", assets_dir, "OG image missing")
+        if known_archetype and args["archetype"] in PUBLIC_PRICING_ARCHETYPES:
+            pricing_info = require_file(results, pages_dir / "pricing.md", "pricing.md", 2)
+            if pricing_info:
+                required_infos.append(pricing_info)
+        elif args["archetype"] not in PUBLIC_PRICING_ARCHETYPES:
+            skip(results, pages_dir / "pricing.md", "archetype does not require pricing.md")
+    else:
+        skip(results, run_dir / "comp/index.html", "handoff mode: the design tool owns the build")
+        skip(results, run_dir / "comp/rounds.md", "handoff mode: the design tool owns the build")
+        skip(results, pages_dir / "index.html", "handoff mode: the design tool owns the build")
+        skip(results, pages_dir / "theme.css", "handoff mode: the design tool owns the build")
+        skip(results, pages_dir / "llms.txt", "handoff mode: the design tool owns the build")
+        for rel in HANDOFF_FILES:
+            info = require_file(results, handoff_dir / rel, rel, 1)
+            if info:
+                required_infos.append(info)
+        assets_info = require_dir(results, handoff_dir / "assets", "handoff assets", 1)
+        if assets_info:
+            required_infos.append({"path": handoff_dir / "assets"})
+
+    if known_archetype and args["archetype"] in FORM_CENTRIC_ARCHETYPES:
+        page_spec_text = read_text(run_dir / "page-spec.md")
+        if isinstance(page_spec_text, OSError):
+            pass
+        elif has_form_design(page_spec_text):
+            emit(results, "PASS", run_dir / "page-spec.md:form", "form design block present")
+        else:
+            emit(results, "FAIL", run_dir / "page-spec.md:form", "form-centric archetype requires a form-design block")
+    elif args["archetype"] not in FORM_CENTRIC_ARCHETYPES:
+        skip(results, run_dir / "page-spec.md:form", "archetype is not form-centric")
+
+    for info in list(required_infos):
+        path = info["path"]
+        if not path.is_file():
+            continue
+        text = info.get("text")
+        if text is None:
+            text = read_text(path)
+            if isinstance(text, OSError):
+                emit(results, "FAIL", path, "unreadable required artifact", str(text))
+                continue
+        if path == run_dir / "voc.md":
+            for why, ctx in parse_voc(text):
+                emit(results, "FAIL", "%s" % path, why, ctx)
+        elif path == run_dir / "message-architecture.md":
+            problems = parse_message_architecture(text)
+            for why in problems:
+                emit(results, "FAIL", path, why)
+        elif path == run_dir / "persuasion-map.md":
+            for why in parse_persuasion_map(text):
+                emit(results, "FAIL", path, why)
+        elif path == run_dir / "page-spec.md":
+            for why in parse_page_spec(text, args["archetype"]):
+                emit(results, "FAIL", path, why)
+        elif path == run_dir / "copy" / "copy-approved.md":
+            for why in parse_copy_approved(text):
+                emit(results, "FAIL", path, why)
+        elif path == run_dir / "conversion-audit.md":
+            problems, warns = parse_conversion_audit(text)
+            for why in problems:
+                emit(results, "FAIL", path, why)
+            for why in warns:
+                emit(results, "WARN", path, why)
+
+    snapshot_text = read_text(run_dir / "copy" / "copy-approved.md")
+    snapshot_title = None
+    if not isinstance(snapshot_text, OSError):
+        snapshot_title = extract_snapshot_title(snapshot_text)
+
+    if args["mode"] in ("build", "explore"):
+        index_text = read_text(pages_dir / "index.html")
+        if not isinstance(index_text, OSError):
+            problems, actual_title = parse_index_html(index_text, snapshot_title)
+            for why in problems:
+                if why == "title mismatch":
+                    emit(
+                        results,
+                        "FAIL",
+                        pages_dir / "index.html",
+                        why,
+                        "snapshot=%s built=%s" % (snapshot_title, actual_title),
+                    )
+                else:
+                    emit(results, "FAIL", pages_dir / "index.html", why)
+
+    log_path = run_dir / "foundry-log.md"
+    log_text = read_text(log_path)
+    log_entries = []
+    if isinstance(log_text, OSError):
+        if args["closing"]:
+            emit(results, "FAIL", log_path, "foundry-log.md required under --closing", str(log_text))
+        else:
+            emit(results, "WARN", log_path, "foundry-log.md missing on first run", str(log_text))
+    else:
+        emit(results, "PASS", log_path)
+        log_entries, problems = parse_foundry_log(log_text)
+        for subject, why, ctx in problems:
+            emit(results, "FAIL", subject, why, ctx)
+        # Degraded-claim cross-check (Gate 0, third bullet): a phase reported
+        # degraded because its companion was "missing" is a FAIL if that
+        # companion resolves PRESENT in preflight.md and was not overridden.
+        for entry in log_entries:
+            degraded = entry["fields"].get("degraded", "")
+            if not degraded or degraded.strip().lower() in ("none", "-"):
+                continue
+            for companion in re.findall(r"[A-Za-z][A-Za-z0-9_-]+", degraded):
+                c = companion.lower()
+                if c in pf_states and companion_available(pf_states, pf_override, c):
+                    emit(results, "FAIL", "%s:%s" % (log_path, entry["date"]),
+                         "degraded claim names '%s' but preflight recorded it PRESENT and un-overridden" % c,
+                         degraded[:80])
+        if args["closing"]:
+            today = date.today().isoformat()
+            matched = False
+            for entry in log_entries:
+                if entry["date"] == today and entry["mode"] == args["mode"] and entry["archetype"] == args["archetype"]:
+                    matched = True
+                    break
+            if matched:
+                emit(results, "PASS", "%s:%s" % (log_path, today), "matching closing entry present")
+            else:
+                emit(results, "FAIL", log_path, "missing today-dated closing entry for mode/archetype", today)
+
+    if args["mode"] == "handoff":
+        copy_text = read_text(run_dir / "copy" / "copy-approved.md")
+        shipped_copy = read_text(handoff_dir / "01-copy.md")
+        if not isinstance(copy_text, OSError) and not isinstance(shipped_copy, OSError):
+            if normalize_text(copy_text) == normalize_text(shipped_copy):
+                emit(results, "PASS", handoff_dir / "01-copy.md", "content matches copy-approved.md")
+            else:
+                missing_lines = []
+                for line in normalize_text(copy_text).splitlines():
+                    if line not in normalize_text(shipped_copy):
+                        missing_lines.append(line[:80])
+                if missing_lines:
+                    emit(results, "FAIL", handoff_dir / "01-copy.md", "diverges from copy/copy-approved.md", missing_lines[0])
+
+    package_dir = handoff_dir if args["mode"] == "handoff" else None
+    check_duplicate_hashes(results, [info for info in required_infos if Path(info["path"]).is_file()], package_dir)
+
+    stale_edges = []
+    if newest_token:
+        token_source = newest_token
+    else:
+        token_source = None
+    stale_edges.extend(
+        [
+            (run_dir / "message-architecture.md", brief_path),
+            (run_dir / "message-architecture.md", run_dir / "voc.md"),
+            (run_dir / "persuasion-map.md", brief_path),
+            (run_dir / "persuasion-map.md", run_dir / "voc.md"),
+            (run_dir / "page-spec.md", run_dir / "message-architecture.md"),
+            (run_dir / "page-spec.md", run_dir / "persuasion-map.md"),
+            (run_dir / "copy" / "approved-draft.md", run_dir / "page-spec.md"),
+            (run_dir / "copy" / "approved-draft.md", run_dir / "message-architecture.md"),
+            (run_dir / "copy" / "copy-approved.md", run_dir / "copy" / "approved-draft.md"),
+            (run_dir / "copy" / "copy-approved.md", run_dir / "copy" / "hero-candidates.md"),
+        ]
+    )
+    if site_context_info:
+        stale_edges.append((run_dir / "page-spec.md", run_dir / "site-context.md"))
+    if token_source:
+        stale_edges.append((run_dir / "comp" / "index.html", token_source))
+        stale_edges.append((run_dir / "copy" / "copy-approved.md", token_source))
+        if args["mode"] in ("build", "explore"):
+            stale_edges.append((pages_dir / "theme.css", token_source))
+        if args["mode"] == "handoff":
+            stale_edges.append((handoff_dir / "03-design-direction.md", token_source))
+    if args["mode"] in ("build", "explore"):
+        stale_edges.extend(
+            [
+                (run_dir / "comp" / "index.html", run_dir / "copy" / "approved-draft.md"),
+                (run_dir / "comp" / "index.html", run_dir / "page-spec.md"),
+                (run_dir / "copy" / "copy-approved.md", run_dir / "comp" / "index.html"),
+                (pages_dir / "index.html", run_dir / "copy" / "copy-approved.md"),
+                (pages_dir / "index.html", run_dir / "page-spec.md"),
+                (run_dir / "conversion-audit.md", pages_dir / "index.html"),
+            ]
+        )
+    else:
+        stale_edges.extend(
+            [
+                (handoff_dir / "01-copy.md", run_dir / "copy" / "copy-approved.md"),
+                (handoff_dir / "02-page-spec.md", run_dir / "page-spec.md"),
+                (run_dir / "conversion-audit.md", handoff_dir / "01-copy.md"),
+            ]
+        )
+    if args["closing"]:
+        stale_edges.append((run_dir / "foundry-log.md", run_dir / "conversion-audit.md"))
+    for target, source in stale_edges:
+        if not Path(source).exists():
+            continue
+        check_stale(results, target, source, args["tolerance"])
+
+    fail_count = 0
+    for status, line in results:
+        print(line)
+        if status == "FAIL":
+            fail_count += 1
+    return fail_count
+
+
+def main(argv):
+    try:
+        args = build_arg_state(argv)
+        if args is None:
+            return 2
+        if isinstance(args, int):
+            return args
+        fail_count = audit_run(args)
+        if fail_count:
+            print("\n%d hard failure(s). Review WARN lines by hand; the chain is not mechanically intact." % fail_count)
+            return 1
+        print("\nChain intact. Orchestration gate passed (review any WARN lines by hand).")
+        return 0
+    except Exception as exc:
+        print("ERROR  %s" % exc, file=sys.stderr)
+        return 2
+
+
+# Limits:
+# - This cannot detect an artifact whose structure looks valid but whose content is
+#   still garbage, lorem ipsum, or strategically empty.
+# - This cannot prove whether a companion skill was truly invoked versus an agent
+#   hand-writing the artifact; no tool-call ledger exists in the audited files.
+# - This cannot verify whether a VOC source pointer is genuine or reachable; that
+#   would require network access, which this script does not use.
+# - This cannot prove that a MECLABS score was produced cold in a fresh context.
+# - This cannot prove that humanizer, red-team, or pattern passes actually ran.
+# - This cannot prove deep semantic consistency between artifacts, such as whether
+#   the built sections actually carry the message-architecture claims forward.
+# - This cannot treat mtime as tamper-proof: mtimes are forgeable with touch-like
+#   tools and are often destroyed by copy or checkout operations, so ordering is a
+#   defect detector for honest runs, not an anti-adversary control. As of the #38
+#   calibration, mtime inversion is a WARN, never a HARD FAIL: a source edited
+#   after its derived artifact (a late provenance note, a brief correction) is
+#   indistinguishable by mtime alone from a genuinely stale derivation, so it
+#   cannot gate a ship. It is surfaced for a human to read.
+#
+# HARD FAIL (blocks the chain) = presence, non-triviality, declared-mode
+#   completeness, and unambiguous integrity (unresolved [TK, foundry-log that
+#   does not parse in the SKILL.md:351 format, a required artifact missing).
+#   These are deterministic and do not false-positive on honest runs.
+# WARN (human reads) = mtime ordering, optional/enhancer artifacts, and format
+#   breakdowns documented for a different file than the one being read.
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))