# How Hallmark Performs Pre-Flight Scanning of Existing Projects

> Discover how Hallmark executes pre-flight scanning on existing projects. It uses a deterministic workflow with a 57-gate anti-slop test and caches results for rapid reuse.

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

---

**Hallmark performs pre-flight scanning through a deterministic, cache-aware workflow that gathers project metadata, runs a 57-gate anti-slop test, and stores results in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) for fast reuse.**

Hallmark's pre-flight scan is the first operation executed when auditing or redesigning any existing codebase. This process, implemented in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), extracts structural and configuration data, validates it against Hallmark's anti-slop consensus, and persists the outcome to avoid redundant work on subsequent runs.

## The Five-Step Pre-Flight Scanning Workflow

### 1. Entry Point and Command Invocation

Pre-flight scanning initiates when you run any Hallmark inspection command. The two primary triggers are:

- `hallmark audit <target>`
- `hallmark redesign <target>`

Upon invocation, Hallmark immediately checks for a hidden `.hallmark` directory in the project root. This folder serves as the persistent storage location for all scan-related artifacts.

### 2. Cache Validation to Skip Redundant Work

Before performing any file system traversal, Hallmark validates its existing cache. According to [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (lines 177-180), the cache check compares **modification times (`mtimes`)** of two critical configuration files:

- [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)
- Any `tailwind.config.*` file

If neither file is newer than [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json), Hallmark loads the cached results and skips the full scan entirely. This optimization ensures near-instant re-runs on unchanged projects.

```bash

# Run a pre-flight audit on the current directory

hallmark audit .

# Inspect the generated cache file

cat .hallmark/preflight.json | jq .

```

### 3. Project Metadata Collection

When the cache is stale or missing, Hallmark performs a comprehensive filesystem walk. The scanning logic in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) extracts the following data points:

- **Macro-structure** — HTML/CSS structural declarations (e.g., macro-structure comments)
- **Theme information** — Color palettes and type-pairings
- **Component usage** — Detection of Hallmark's 50 archetype components
- **Tailwind configuration** — Colors, spacing scales, and typography settings
- **Package metadata** — Scripts and dependencies from [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)

The client-side JavaScript builds a structured JSON payload containing all extracted metadata, preparing it for the validation phase.

### 4. The 57-Gate Slop-Test Validation

After data collection, Hallmark executes its signature **anti-slop consensus** — a 57-gate validation suite. Each gate enforces a specific design quality rule covering:

- Typography hierarchy and legibility
- Color contrast ratios
- Layout consistency patterns
- Motion and animation behavior
- Interaction feedback states

The test implementation is located in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) around line 471. Results from all 57 gates are appended to the JSON payload as the `slopResults` field.

### 5. Cache Persistence for Subsequent Runs

The final step writes the complete data object to [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json). The cache structure includes:

- Extracted project metadata
- Slop-test pass/fail results per gate
- Timestamps for cache invalidation

On future invocations, Hallmark reloads this file and repeats the mtime validation from step 2, creating an efficient incremental workflow.

## Core Implementation: Cache Logic in site/js/main.js

The pre-flight orchestration follows this pattern, simplified from the actual source:

```javascript
async function runPreflight(projectRoot) {
  const cachePath = path.join(projectRoot, ".hallmark", "preflight.json");

  // Reuse cache if package.json and tailwind.config haven't changed
  if (await isCacheValid(cachePath, ["package.json", "tailwind.config.js"])) {
    return JSON.parse(await readFile(cachePath, "utf8"));
  }

  // Fresh scan: collect all project metadata
  const data = await collectProjectMetadata(projectRoot);

  // Validate against 57 anti-slop rules
  data.slopResults = await runSlopTest(data);

  // Persist for next run
  await writeFile(cachePath, JSON.stringify(data, null, 2));
  return data;
}

```

This deterministic approach ensures that **expensive file system operations and slop-test execution occur only when source configurations actually change**.

## Key Source Files Supporting Pre-Flight Scanning

| File | Purpose |
|------|---------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Documents the persistence strategy and [`preflight.json`](https://github.com/Nutlope/hallmark/blob/main/preflight.json) format |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Implements scanning, slop-test execution, and cache I/O |
| [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) | Describes overall workflow including "pre-emit self-critique" |
| [`skills/hallmark/references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) | References cached [`preflight.json`](https://github.com/Nutlope/hallmark/blob/main/preflight.json) for hero image enrichment |

## How Cached Data Drives Downstream Workflows

The pre-flight scan is not merely a diagnostic step — it powers Hallmark's core capabilities:

1. **Audit reports** — Display slop-test failures with specific gate references
2. **Redesign mode** — Use detected component usage and theme values as transformation constraints
3. **Hero enrichment** — Leverage cached metadata to generate contextually appropriate imagery

All operations that would otherwise require repeated file analysis instead read from the validated cache.

## Summary

- **Pre-flight scanning** triggers on `hallmark audit` or `hallmark redesign` commands
- **Cache validation** uses mtime comparison of [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) and `tailwind.config.*` to skip unnecessary work
- **Metadata extraction** covers structure, theme, components, Tailwind values, and package data
- **57-gate slop-test** validates against anti-slop rules for typography, color, layout, motion, and interaction
- **Deterministic caching** stores results in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) for sub-second subsequent runs

## Frequently Asked Questions

### What triggers a fresh pre-flight scan instead of cache reuse?

A fresh scan occurs when [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) is missing, or when [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) or any `tailwind.config.*` file has been modified more recently than the cache file. Hallmark compares modification timestamps to detect staleness.

### What design aspects does the 57-gate slop-test evaluate?

The slop-test gates cover typography hierarchy, color contrast ratios, layout consistency, animation motion, and interaction feedback. Each gate returns a pass/fail result that contributes to the overall anti-slop validation.

### Can I manually clear the pre-flight cache?

Yes. Delete the [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) file or the entire `.hallmark` directory. The next Hallmark command will automatically regenerate the cache with fresh scan data.

### Where is the pre-flight scanning logic implemented?

The core implementation resides in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), which handles filesystem traversal, metadata collection, slop-test execution, and cache read/write operations. The caching strategy is documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).