SYS.02 / MODEL
The four words
Project, source, snapshot, run. Every other chapter assumes these, and three of them are routinely confused.
The nouns
What each one owns, and what it deliberately does not.
- Project
- The durable thing you name and come back to. It holds sources, snapshots, Skills and settings. It is not a repository — one project can be fed by a repository today and an upload tomorrow.
- Source
- Where the code comes from: a connected GitHub repository, a public repository URL, or an uploaded archive. A project may have more than one over its life.
- Snapshot
- One frozen reading of the source: a file index, content-addressed blobs, and a content root hash. Everything downstream is scoped to a snapshot, which is what makes a claim re-checkable months later.
- Run
- One execution of the pipeline over one snapshot, as a queue of steps with their own states. A step that fails is a failed step, not a failed product — later steps that do not depend on it still run.
Why everything hangs off a snapshot
A claim about a moving repository cannot be checked.
A Skill that says "the payments module has no tests" is either true of something specific or it is decoration. Attached to a snapshot, it is a statement about a file index somebody can go and look at. Attached to "your repo", it decays the moment anyone pushes.
This is also what makes change sets possible: two snapshots of the same project can be compared, and what changed between them is a fact rather than a summary. See Snapshots and change.
Reading a status
Five words that look interchangeable and are not.
| Word | The check ran? | What is being claimed |
|---|---|---|
| PASS | yes | It evaluated the condition and the condition held |
| WARN | yes | It found something worth looking at, not a certainty |
| FAIL | yes | The condition it checks was met |
| UNKNOWN | yes | It could not decide. A result, not a gap |
| NOT_SUPPORTED | no | It does not apply to this project, or cannot be done here |
Every term the product uses is defined in the glossary, alongside how it would be said in ordinary language.