How to Use the Hallmark Audit Command to Score Existing Code

The hallmark audit command evaluates HTML files against a catalog of anti-patterns and structural rules, producing a severity-grouped report that identifies AI-generated "slop" and provides specific fixes.

The hallmark audit command is a read-only verb in the Nutlope/hallmark CLI that scores existing code by detecting tells, validating structural fingerprints, and enforcing design system constraints. According to the source code in [skills/hallmark/references/verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), the command extracts Hallmark stamps from your files, checks them against the anti-pattern catalog, and returns a verdict ranging from "ships as slop" to "close, fix the minors."

What the Hallmark Audit Command Evaluates

When you invoke hallmark audit, the tool performs four distinct validation passes defined in the verb specification.

Anti-Pattern Detection

The command matches your code against the canonical list of tells stored in [skills/hallmark/references/anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). Each tell carries a severity label:

• Critical: Fundamental structural flaws (e.g., gradient heroes on landing pages)
• Major: Design inconsistencies (e.g., using Inter for both display and body text)
• Minor: Typographic details (e.g., straight quotes instead of curly)

Structural Fingerprint Analysis

The audit extracts Hallmark comment stamps—formatted as /* Hallmark · macrostructure: <name> · … */ or HTML <!-- Hallmark · … -->—and validates whether the actual DOM structure matches the declared macrostructure. If you stamp a page as macrostructure: Split Hero but the DOM shows a centered hero with three feature cards, the audit flags a critical structural finding ("stamp lies").

Running hallmark audit on Your Codebase

Execute the command against single files or glob patterns. The CLI entry point is registered in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which declares the verb availability.

Audit a specific HTML file:

npx hallmark audit path/to/file.html

Audit an entire directory:

npx hallmark audit src/pages/**/*.html

If the Hallmark CLI is installed globally, omit the npx prefix.

Understanding the Audit Report Format

The output format is defined in lines 4‑16 of [audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md). Results appear grouped by severity with file paths and line numbers:

[critical] The purple-gradient hero — site/example.html:8
  Reason: gradient hero is a slop tell
  → Fix: pick a single accent hue, no hero gradient

[major] Inter-everywhere — site/example.html:23
  Reason: Inter used for both display & body
  → Fix: pair a distinctive display face with a refined body face

Summary — 1 critical · 1 major · 1 minor
Verdict — ships as slop

Interpreting the Verdict

The audit concludes with one of three standardized verdicts:

• ships as slop: At least one critical anti-pattern exists. Redesign before publishing.
• reads as AI-generated: Only major and minor tells detected. Refine the flagged elements.
• close, fix the minors: No critical issues; apply minor suggestions to reach compliance.

Genre-Aware and Design System Validation

Beyond static rules, the audit applies contextual overrides based on project configuration.

Genre Overrides

If your stamp declares a genre (e.g., genre: atmospheric), the audit consults [skills/hallmark/references/slop-test.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) for genre-specific allowances. Atmospheric genres may permit radial-gradient backgrounds that standard landing pages cannot use, though critical tells still trigger violations.

Design.md Integration

When the project root contains design.md or DESIGN.md, the audit enforces theme-drift, macrostructure-family, and stamp-match rules as specified in lines 18‑24 of [audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md). This ensures individual pages align with the project-wide design system defined in your documentation.

Practical Examples

Auditing with Custom Stamps

If your HTML contains a custom stamp:

<!-- Hallmark · macrostructure: Bento Grid · genre: atmospheric -->

The audit applies atmospheric overrides while still flagging critical tells that contradict the stamp or genre.

Sample Output Walkthrough

Running hallmark audit on a file with multiple issues produces structured feedback:

[critical] The purple-gradient hero — file.html:12
  Reason: gradient hero is a slop tell
  → Fix: use a single-anchor hue, no gradient

[major] Inter-everywhere — file.html:45
  Reason: same font for display & body
  → Fix: pair a distinctive display face with a refined body face

[minor] Straight quotes — file.html:54
  Reason: typographic inconsistency
  → Fix: use curly quotes

Summary — 1 critical · 1 major · 1 minor
Verdict — ships as slop

Summary

• Install and run: Use npx hallmark audit <path> to evaluate files or glob patterns.
• Check critical first: Address [critical] findings immediately to avoid "ships as slop" verdicts.
• Leverage stamps: Include Hallmark stamps in your HTML to activate genre-aware rules from slop-test.md.
• Validate against design.md: Place a design.md in your project root to enforce macrostructure-family consistency.
• Iterate: Re-run the command after fixes until the verdict reads "reads as AI-generated" or "close, fix the minors."

Frequently Asked Questions

What file types does hallmark audit support?

The command primarily evaluates HTML files, but it will scan any file containing Hallmark stamps. The parser looks for HTML comment stamps (<!-- Hallmark · … -->) or JavaScript-style block comments (/* Hallmark · … */) to extract macrostructure and genre metadata before applying rules from anti-patterns.md.

How does hallmark audit detect if code is AI-generated "slop"?

The command checks for structural tells defined in [skills/hallmark/references/anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md)—such as "The purple-gradient hero" or "Inter-everywhere"—and validates whether the DOM matches the declared macrostructure in your Hallmark stamp. Mismatches between stamps and actual structure trigger critical findings.

Can I customize which anti-patterns the audit flags?

No. The audit verb uses the fixed catalog in anti-patterns.md and the algorithm in audit.md. However, you can influence scoring by adding a design.md file to your project root; lines 18‑24 of the audit specification show that the verb enforces project-specific theme-drift and macrostructure-family rules when this file is present.

What is the difference between the three verdicts?

"ships as slop" means critical anti-patterns exist that require redesign before publication. "reads as AI-generated" indicates acceptable structure with only major/minor refinement needed. "close, fix the minors" signals the page meets quality standards aside from small typographic or cosmetic issues.

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