# How to Use the Hallmark Audit Command to Score Existing Code

> Learn to use the hallmark audit command to score existing code. This tool evaluates HTML files against anti-patterns, identifies AI-generated slop, and offers specific fixes for better code quality.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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)](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)](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)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which declares the verb availability.

Audit a specific HTML file:

```bash
npx hallmark audit path/to/file.html

```

Audit an entire directory:

```bash
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/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:

```text
[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)](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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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/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:

```html
<!-- 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:

```text
[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`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md).
- **Validate against design.md**: Place a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and the algorithm in [`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md). However, you can influence scoring by adding a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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.