Projects and revisions

A project evolves through revisions. A revision is an immutable snapshot of accepted product intent plus its relationship to the preceding revision.

Why revisions matter

Without revision identity, “regenerate” is only another build command. A reliable system must answer:

• Which product intent produced this artifact?
• What changed since the previous release?
• Which generator version interpreted it?
• Which schema transition belongs to it?
• Which tests and approvals supported promotion?

Revisions make these questions data rather than archaeology.

Revision contents

A revision records or references:

• the complete normalized Evolutionary Model;
• its parent revision;
• timestamps and authoring provenance;
• explicit decisions and acknowledgements;
• the experience blueprint fingerprint;
• generation inputs such as targets and add-ons;
• derived hashes used to identify stale projections.

Conversation history can explain how a decision was reached, but the normalized model—not the transcript—is the generation input.

Derived artifacts

Generated source, MODEL.md, DESIGN.md, previews, migration bundles, and release records are derived from a revision. Each should retain the revision identifier and generator version.

If two artifacts claim the same inputs but differ semantically, the generator contract has been violated or undeclared input entered the build.

Editing and saving

Edits occur against a working project state. Saving an accepted change produces or updates the next revision according to the product workflow; already released revisions remain immutable.

Use descriptive revision summaries that express intent:

Good: Restrict patient cancellation to 24 hours before appointment
Weak: Update forms and API

The first description survives changes in implementation.

Branching and collaboration

When parallel product changes are supported, branches must merge model intent, not generated folders. Conflicts should be reported in domain terms: two changes altered the same permission, lifecycle, or experience decision.

The generated result is rebuilt after the model merge. Merging generated output first would reintroduce a competing source of truth.

Reproducing a candidate

To reproduce a candidate, resolve:

revision + generator version + target configuration + declared build inputs

Live secrets and data are intentionally excluded. They are runtime authorities and are injected or restored separately.

Continue with the Lifecycle or Evolutionary Model reference.