What Is the Purpose of `.hallmark/log.json` in the Hallmark Repository?

.hallmark/log.json is Hallmark's project-level memory file that records each generation run in a JSON array, enforcing automatic diversification by preventing consecutive builds from reusing the same macrostructure, theme, or enrichment combination.

In the Nutlope/hallmark open-source project, .hallmark/log.json persists at the project root as the canonical history of every page generation. This durable record drives the diversification engine that keeps successive outputs visually distinct. Understanding the purpose of .hallmark/log.json is essential for developers who want to customize Hallmark's behavior or audit its rotation logic.

How .hallmark/log.json Stores Project Memory

The log file is a JSON array ordered with the newest entry first. Each entry captures the essential choices that defined a single generation run, enabling Hallmark to compare future runs against recent history.

Required Fields for Every Entry

Every standard entry written to .hallmark/log.json includes the following fields:

• date — ISO date string recording when the run occurred.
• macrostructure — Name of the macrostructure layout archetype applied to the page.
• theme — Selected theme name, or the string "custom" for handcrafted themes.
• enrichment — Hero enrichment that was added, such as a specific effect name or "none".
• brief — One-line summary describing the generation brief.

Custom Run Metadata

When a custom theme is generated, the entry expands to include additional axes that describe the aesthetic direction:

• theme_axes — The three defining axes: paper-band, display-style, and accent-hue.
• vibe — An optional string describing the custom aesthetic vibe.

These fields are documented in skills/hallmark/references/custom-theme.md under the project-memory specification.

Diversification Rules and Rotation Policy

According to skills/hallmark/SKILL.md, Hallmark reads .hallmark/log.json at the start of every new run to enforce the diversification rule. Consecutive runs in the same project must differ on at least one recorded axis, such as macrostructure, theme, or enrichment, which prevents repetitive output.

After a successful generation, Hallmark appends a new entry to the front of the array and trims the history to the most recent 20 entries. If the .hallmark/ directory or the log file does not exist, Hallmark creates them automatically while respecting .gitignore settings.

Working with .hallmark/log.json in Code

The repository's design documents imply a straightforward lifecycle for interacting with the log: read existing history, make a diversification-aware decision, and write a new record.

Reading the Log File

The following Node.js snippet reads the existing log or returns an empty array if the project has no generation history yet:

import { readFileSync } from 'fs';
import path from 'path';

const LOG_PATH = path.resolve('.hallmark/log.json');

function readLog() {
  try {
    const raw = readFileSync(LOG_PATH, 'utf-8');
    return JSON.parse(raw);
  } catch (e) {
    // No log yet → start with empty array
    return [];
  }
}

// Example: get the most recent macrostructure
const log = readLog();
const latestMacro = log[0]?.macrostructure ?? 'none';
console.log('Previous macrostructure:', latestMacro);

Appending a New Entry

After generating a page, you can persist the run to .hallmark/log.json by inserting a new object at the front of the array and limiting the history to 20 items:

import { writeFileSync } from 'fs';
import path from 'path';

function writeLogEntry(entry) {
  const LOG_PATH = path.resolve('.hallmark/log.json');
  const log = readLog();               // reuse function from above
  const updated = [entry, ...log].slice(0, 20); // keep only 20 newest
  writeFileSync(LOG_PATH, JSON.stringify(updated, null, 2));
}

// Create a new entry after a run
writeLogEntry({
  date: new Date().toISOString().split('T')[0],
  macrostructure: 'hero-grid-3-cols',
  theme: 'carnival',
  enrichment: 'E2-parallax-hero',
  brief: 'Launch page for summer festival',
  // custom runs also add:
  // theme_axes: 'paper-band / display-style / accent-hue',
  // vibe: 'bright-playful'
});

Enforcing Diversification Constraints

To respect the diversification rule in your own tooling, compare candidate choices against recent entries. The example below checks whether a macrostructure was used in the last three runs:

function canUseMacro(macro) {
  const recent = readLog().slice(0, 3); // look at last three runs
  return !recent.some(entry => entry.macrostructure === macro);
}

// Example guard
if (!canUseMacro('hero-grid-3-cols')) {
  console.warn('Macrostructure recently used – picking a different one.');
}

Key Source Files for .hallmark/log.json

The behavior and schema of .hallmark/log.json are defined across several files in the Nutlope/hallmark repository:

• skills/hallmark/SKILL.md — Primary specification of the log format, append logic, and diversification rule.
• skills/hallmark/references/custom-theme.md — Detailed schema for custom-theme entries, including theme_axes and vibe.
• skills/hallmark/references/verbs/redesign.md — Documents how audit and redesign steps check the log for prior runs.
• .gitignore — Declares the .hallmark/ directory as ignored by default, confirming the log is intended as local project memory rather than version-controlled source.
• site/_tests/README.md — References the log as part of the project memory test suite.

Summary

• .hallmark/log.json is a project-level JSON array that records every Hallmark generation run with fields like date, macrostructure, theme, enrichment, and brief.
• Diversification enforcement requires consecutive runs to differ on at least one axis, which Hallmark validates by reading the log before each new generation.
• Automatic rotation keeps the array trimmed to the newest 20 entries, with the most recent record inserted at the front.
• Custom runs append theme_axes and vibe to support aesthetic rotation across handcrafted themes.
• Local-only storage is guaranteed because Hallmark creates .hallmark/ automatically and the directory is ignored by Git.

Frequently Asked Questions

Where is .hallmark/log.json located?

The file resides at the project root inside the .hallmark/ directory. Hallmark creates this folder and the log automatically if they do not exist, and the directory is typically listed in .gitignore to keep generation history out of version control.

What happens if I delete .hallmark/log.json?

Removing the log resets the project's generation history. The next run will start with an empty memory state, so Hallmark will not enforce diversification against prior runs that are no longer recorded.

How does Hallmark use the log to prevent repetitive themes?

Before selecting a macrostructure or theme, Hallmark reads the existing .hallmark/log.json array and verifies that the new choices differ from the most recent entry on at least one axis. This rule is codified in skills/hallmark/SKILL.md and prevents consecutive builds from producing identical layout and style combinations.

Why does the log only keep 20 entries?

The 20-entry rotation policy balances historical context with file size. According to the project-memory specification in skills/hallmark/SKILL.md, trimming older entries ensures that long-running projects do not accumulate an unwieldy history while still retaining enough recent context to enforce meaningful diversification.

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