Managing xspec Workspace Files with Git

Understand which xspec output files are derived vs durable, what to commit, how to configure .gitignore, and how staleness detection works.

Every file that xspec writes has deterministic bytes — stable ordering, sorted keys, no timestamps, no absolute paths. This means derived files are safe to commit (they diff cleanly), safe to regenerate (rebuilding produces the same result), and safe to check for staleness in CI. Understanding the distinction between derived and durable files tells you what you must commit and what you may optionally regenerate.

File inventory

For a source file at specs/AUTH.mdx, xspec produces the following files:

Path	What it contains	Class
specs/AUTH.xspec.ts	Generated TypeScript module	Derived
specs/AUTH.xspec.impl.js	Runtime implementation	Derived
specs/AUTH.xspec.impl.d.ts	Types and hover documentation	Derived
specs/AUTH.xspec.impl.d.ts.map	Declaration map (go-to-definition into .mdx)	Derived
specs/AUTH.md	Pure Markdown (only emitted when markdown.emit is enabled)	Derived
.xspec/graph.json	Graph data used by check, ids, show, coverage, impact, review, and query	Derived
.xspec/journal	Identity journal for rename and move	Durable
.xspec/reviews/<name>.json	Review sessions	Durable

Derived vs durable

Derived files are fully reproducible from your source MDX files, your xspec configuration, and the journal. If a derived file is missing, corrupted, or stale, run xspec build to regenerate it. You can always trust a rebuild to produce the same bytes for the same inputs.

Durable files are written only by specific xspec commands (xspec rename, xspec move for the journal; xspec review create, xspec review resolve, etc. for sessions). They are never regenerated and must not be modified by hand. If a durable file is lost or corrupted, you must restore it from version control — there is no rebuild path.

What to commit

Journal and review sessions — non-negotiable

The journal (.xspec/journal) maps old node identities to new ones. Losing it breaks baseline comparisons for every consumer of your repository. Review sessions record work in progress that cannot be reconstructed. Both must be committed without exception.

Do not add .xspec/ to .gitignore wholesale. Doing so would ignore the journal and review sessions, silently destroying identity continuity and review history.

Generated TypeScript modules and companions

The generated TypeScript module (*.xspec.ts) and its companion files (*.xspec.impl.js, *.xspec.impl.d.ts, *.xspec.impl.d.ts.map) are what downstream consumers import. Committing them means consumers can resolve ./NAME.xspec without running xspec themselves.

Running xspec check in CI proves that committed generated files match current sources. This gives you a clean two-step: commit the files, verify they are up to date in CI.

Emitted Markdown and graph.json

You have two options for specs/**/*.md and .xspec/graph.json:

• Commit them — the same reasoning applies as for generated modules. Consumers and tooling can use them without a build step, and xspec check validates staleness.
• Ignore them and rebuild in CI — add them to .gitignore and run xspec build as the first CI step before xspec check. This keeps the repository smaller at the cost of a build step on every CI run.

Both approaches are correct. Choose based on your team’s preference for repository size vs CI simplicity.

.gitignore for the regenerate-in-CI policy

If you choose to regenerate derived files in CI rather than committing them, use this pattern:

# Derived files — rebuilt by `xspec build` in CI
# IMPORTANT: do NOT ignore .xspec/ wholesale — journal and reviews are durable
*.xspec.*
specs/**/*.md
.xspec/graph.json

The pattern *.xspec.* matches the TypeScript module and all companion files. It does not match .xspec/journal or .xspec/reviews/ because those paths do not contain .xspec. with a trailing dot.

Staleness detection

xspec check compares each derived file against what xspec build would produce for the current sources. A stale file produces an error like:

specs/AUTH.xspec.ts: stale generated output (14.10): … run `xspec build` to regenerate

The version number in parentheses (14.10) identifies the xspec version that generated the file, which helps diagnose staleness caused by an xspec upgrade rather than a source edit.

In CI, run xspec build && xspec check as a single gate. This catches both missing files (not yet generated) and stale files (generated from an older version of sources).

Filesystem behavior

A few properties of xspec’s file I/O are worth knowing when integrating with other tooling:

• Writes are atomic in effect. A partial write will not leave a file in an inconsistent state.
• Mutating commands are mutually exclusive per workspace. Two xspec processes cannot run simultaneous mutations in the same workspace directory.
• Symlinks are never followed during file discovery or when writing output. xspec operates only on real files at their canonical paths.
• No network access. xspec reads from git only where the documentation explicitly states it does (e.g., xspec impact --base), and never writes to git.