How Hallmark Performs Pre-Flight Scanning of Existing Projects

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 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, 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 (lines 177-180), the cache check compares modification times (mtimes) of two critical configuration files:

• package.json
• Any tailwind.config.* file

If neither file is newer than .hallmark/preflight.json, Hallmark loads the cached results and skips the full scan entirely. This optimization ensures near-instant re-runs on unchanged projects.

# 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 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

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 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. 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:

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	Documents the persistence strategy and preflight.json format
site/js/main.js	Implements scanning, slop-test execution, and cache I/O
README.md	Describes overall workflow including "pre-emit self-critique"
skills/hallmark/references/hero-enrichment.md	References cached 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 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 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 is missing, or when 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 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, which handles filesystem traversal, metadata collection, slop-test execution, and cache read/write operations. The caching strategy is documented in skills/hallmark/SKILL.md.

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