How Hallmark Enforces Diversification of Macrostructures: A Technical Deep Dive

Hallmark guarantees that consecutive pages never reuse the same macrostructure by implementing a layered system of CSS stamps, log tracking, and slop-test gates that enforce categorical distinctness between builds.

Hallmark is an open-source skill for generating structured web pages that treats diversification of macrostructures as a core constraint rather than a stylistic preference. According to the Nutlope/hallmark source code, the system employs multiple enforcement mechanisms—from mandatory CSS comments to runtime validation gates—to ensure that no two consecutive outputs in the same project share the same page-level layout architecture.

The Diversification Rule in macrostructures.md

The foundational constraint lives in skills/hallmark/references/macrostructures.md, which explicitly defines that every new macrostructure must be different from the one previously used. Lines 7-10 of this reference file establish the rule: before selecting a macrostructure, Hallmark scans the codebase for any existing stamp, and if found, the selection is constrained to alternatives only.

This reference file serves as the single source of truth for available macrostructures (such as "Bento Grid," "Long Document," "Marquee Hero," and "Stat-Led") and codifies the prohibition against repetition. The rule operates categorically—meaning the system treats macrostructures as distinct architectural patterns that cannot be recycled between consecutive generations.

Runtime Enforcement via Slop-Test Gates

Hallmark validates compliance at build time through its slop-test suite, specifically Gate 8 documented in skills/hallmark/references/slop-test.md (lines 40-45). This gate reads the most recent entry from .hallmark/log.json or inspects the CSS stamp from the previous build. If the proposed macrostructure matches the previous one, the gate aborts the build immediately, preventing identical consecutive outputs from reaching production.

The slop-test acts as a hard stop in the CI/CD pipeline, ensuring that even if other logic fails, the diversification constraint remains inviolable. This runtime validation complements the static rule definition by adding executable enforcement that fails closed rather than open.

Stamp-Based Tracking in CSS Files

Every CSS file generated by Hallmark begins with a mandatory metadata comment that records the selected macrostructure. The stamp follows this exact format:

/* Hallmark · macrostructure: Bento Grid · … */

This macrostructure stamp serves dual purposes: it creates an auditable artifact for the diversification rule to detect, and it persists the architectural decision directly within the generated output. The presence of this stamp is non-optional according to the macrostructures diversification rule, making it impossible to generate a page without declaring its structural type.

Subsequent builds scan existing CSS files for these stamps to determine which macrostructures are already in use, creating a self-documenting constraint system where the generated artifacts carry their own lineage metadata.

Audit and Redesign Verbs

Hallmark exposes the diversification logic through specific verbs that operate on existing pages. The audit verb, defined in skills/hallmark/references/verbs/audit.md (lines 14-25), compares the macrostructure stamp against the actual rendered layout to detect drift or manual overrides that might violate the diversification constraint.

When users request a redesign, the redesign verb documented in skills/hallmark/references/verbs/redesign.md (lines 33-45) invokes the same diversification rule to force a new macrostructure. This ensures that redesign operations produce categorically distinct page architectures rather than mere cosmetic refreshes, preventing "template-swap" copies that preserve the underlying structural monotony.

Log Persistence and State Management

Between builds, Hallmark maintains state in .hallmark/log.json, which records a history of chosen macrostructures with timestamps. After each successful build, the system appends an entry containing the selected macrostructure, creating an append-only audit trail that future runs consult before selection.

The following Node.js implementation demonstrates the complete diversification logic as it appears in the Hallmark source:

// Enforce macrostructure diversification (Node.js)

// 1️⃣ read the current CSS stamp (if any)
const fs = require('fs')
const css = fs.readFileSync('site/example.css', 'utf8')
const stampMatch = css.match(/Hallmark\s·\smacrostructure:\s(\w[\w\s-]+)/)
const currentMacro = stampMatch ? stampMatch[1].trim() : null

// 2️⃣ read the last macrostructure from the log (if it exists)
let lastMacro = null
try {
  const log = JSON.parse(fs.readFileSync('.hallmark/log.json', 'utf8'))
  lastMacro = log[log.length - 1].macrostructure
} catch (_) { /* no log yet */ }

// 3️⃣ pick a new macrostructure that differs from both
const candidates = ['Bento Grid','Long Document','Marquee Hero','Stat‑Led']
const pick = candidates.find(m => m !== currentMacro && m !== lastMacro)

// 4️⃣ abort if we couldn’t find a new one
if (!pick) throw new Error('Diversification rule: no alternative macrostructure available')

// 5️⃣ write the stamp and log entry
const stamp = `/* Hallmark · macrostructure: ${pick} */\n`
fs.writeFileSync('site/example.css', stamp + css.replace(/\/\* Hallmark.*\*\//, ''))
fs.appendFileSync('.hallmark/log.json', JSON.stringify({macrostructure: pick, ts: Date.now()}) + ',\n')

console.log(`Selected macrostructure: ${pick}`)

This persistence layer enables the system to enforce diversification across disconnected build sessions, maintaining architectural variety even when pages are generated days or weeks apart.

Summary

• Constraint is codified in skills/hallmark/references/macrostructures.md, requiring every new macrostructure to differ from the previous one.
• CSS stamps embed the chosen macrostructure as mandatory comments in generated files, creating discoverable metadata.
• Slop-test Gate 8 in skills/hallmark/references/slop-test.md aborts builds that would repeat the last macrostructure.
• Audit and redesign verbs expose diversification logic for maintenance operations, ensuring redesigns produce structural changes, not just cosmetic ones.
• Log persistence in .hallmark/log.json maintains state between builds to prevent repetition across time gaps.

Frequently Asked Questions

What happens if Hallmark cannot find an alternative macrostructure?

If all available macrostructures are already used in recent history and no alternative exists that satisfies the diversification rule, the build throws a fatal error: Diversification rule: no alternative macrostructure available. This hard failure prevents the system from violating its core constraint by repeating a macrostructure.

How does the audit verb detect macrostructure violations?

The audit verb inspects the CSS stamp comment in existing files and compares it against the actual DOM structure rendered by the page. If the stamp claims "Bento Grid" but the layout implements "Long Document" patterns, or if the diversification rule has been bypassed manually, the audit flags the discrepancy for correction.

Can the diversification rule be disabled or overridden?

No. According to the source code in macrostructures.md and the slop-test implementation, the diversification of macrostructures is a non-negotiable constraint. The slop-test gate aborts builds rather than allow repeats, and there is no configuration flag to disable this behavior, as it represents a fundamental guarantee of the Hallmark skill.

Where is the macrostructure history stored between builds?

Hallmark persists the history of used macrostructures in .hallmark/log.json at the project root. Each successful build appends a JSON object containing the macrostructure name and timestamp, which subsequent builds read to enforce the prohibition against consecutive repetition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}