markitect-tool/docs/cache-incremental.md

Lightweight Cache and Incremental Processing

markitect-tool includes a small file-backed cache manifest for the core CLI. It records Markdown file fingerprints and parse summaries so workflows can detect which inputs changed before rerunning expensive operations.

This is intentionally not the future SQLite/AST/query backend. That richer backend is tracked in MKTT-WP-0006 and MKTT-WP-0007.

Commands

Fingerprint one file:

mkt cache fingerprint docs/example.md

Build or refresh a manifest:

mkt cache build docs/ --root .

The default manifest path is:

.markitect/cache/manifest.json

Check status against the manifest:

mkt cache status docs/ --root .

Exit behavior:

• 0: clean
• 1: new, changed, or deleted Markdown files detected

Manifest Contents

Each entry records:

• relative path
• SHA-256 content hash
• size
• modification time
• parser identity
• heading, section, and block counts

The content hash is the authoritative change signal. Modification time and size are recorded for diagnostics and future fast-path checks.

Design Boundary

This layer provides:

• repeatable fingerprints
• changed/new/deleted detection
• simple parse summaries
• a transparent JSON file that can be inspected or removed

It does not provide:

• AST persistence
• JSONPath querying over cached documents
• SQLite/FTS indexes
• vector search
• policy-aware retrieval
• distributed cache synchronization

Those belong to later backend workplans.