Compilation workflow: pre-push hooks, validation, and recipe lifecycle

[thorwhalen]

The problem

reci compiles recipes into GitHub Actions workflows. But once compiled, the recipe and the workflow can drift apart — someone edits the workflow directly, or updates the recipe but forgets to recompile. This silent divergence is error-prone: the workflow runs fine but no longer matches the recipe, and nobody notices until something breaks.

Compilation at push time

One approach: a pre-push git hook (or pre-commit hook) that automatically recompiles the recipe before every push. This gives a "dynamic" feel (always up-to-date) while maintaining the compiled-workflow-on-remote guarantee that GitHub Actions needs.

This is especially valuable during the development phase of a CI pipeline, when the recipe changes frequently — you're iterating, pushing to validate on GitHub (since local tools like ACT don't support everything, e.g., artifacts). Once the CI stabilizes, changes are rare, and the hook becomes a lightweight safety net.

However, compilation-on-push should probably be an opt-in mode, not the default. The rationale:

• Recipes don't change often once stabilized
• For some workflows, the recipe is a one-time input, not a living document kept in the project
• Adding a mandatory compilation step is itself boilerplate — which is what reci aims to reduce

Validation as an alternative to dynamism

Instead of (or in addition to) automatic recompilation, reci can validate that a recipe and its compiled workflow are still aligned:

• File date comparison: If the recipe's mtime is newer than the workflow's, flag it
• Content hash comparison: Store a hash of the recipe in a comment in the compiled workflow; check on validation
• Structural comparison: Parse both and compare the DAG structure, config bindings, etc.

reci already has a validation framework (DAG, FLOW, CONF, PURITY, ACT rules). A new rule category (e.g., SYNC001: recipe/workflow mismatch) would fit naturally.

Recipe lifecycle — where does the recipe live?

Two mental models:

1. Recipe-in-project: The recipe lives alongside the code (e.g., ci/recipe.yml), is versioned, and is the source of truth. The compiled workflow is a derived artifact.
2. Recipe-as-tool: The recipe is a one-time input used to generate the workflow. It may not even live in the project. The workflow is the source of truth.

Both are valid. reci should support both, with the tooling (hooks, validation) available for those who choose model 1, without imposing it on those who prefer model 2.

Best practices for each model

Model 1 (recipe-in-project):

• Keep recipe in a conventional location (ci/recipe.yml, .reci/recipe.yml, or project root)
• Use pre-push hook to recompile automatically
• Use SYNC validation rules to catch drift
• Refactor variable parts into config/parameters so the recipe changes rarely

Model 2 (recipe-as-tool):

• Use reci compile manually when CI needs updating
• The workflow file is the source of truth
• No hooks or sync validation needed
• Recipe may live outside the project or not be versioned at all

Practical next steps

• Provide a reci hook install command that sets up a pre-push hook for automatic recompilation
• Add a SYNC validation rule category for recipe/workflow alignment checks
• Document both lifecycle models and when each makes sense
• Consider decompilation (workflow → recipe) for migration or round-trip validation — this would also help users adopting reci for existing workflows

Open questions

• Should compilation-on-push be the default, or opt-in?
• Where should the recipe conventionally live in a project? (ci/, .reci/, project root?)
• Should reci support decompilation (workflow → recipe)? This is powerful for migration and round-trip validation, but may be out of scope initially.
• How to best balance explicitness in code with AI-driven smoothness? (Skills and agents can smooth over explicit/verbose code, which suggests keeping the compiled output verbose and correct rather than minimizing it.)

Context

From a conversation between @thorwhalen and @valentin-feron. Key insight: during CI development, recipes might change frequently (lots of push-test cycles, especially since ACT doesn't support artifacts). After stabilization, changes are rare. The tooling should serve both phases. But we should encourage parametrization over recipe editing.