Artifact Production Rule¶
Standard ID: ES-APR Status: BINDING Version: 2.0.0 Effective: 2026-07-19
Core Rule¶
Every artifact must have four fields before creation:
| Field | Description |
|---|---|
| Owner | Who maintains this artifact |
| Consumer | Who reads or uses this artifact |
| Lifetime | Permanent, until-merged, until-superseded, delete-after-execution |
| Authoritative Replacement | What system owns this knowledge long-term |
Enforcement Classification¶
Every artifact MUST carry an enforcement classification indicating how correctness is maintained:
| Classification | Meaning | Drift Risk |
|---|---|---|
self-enforcing |
The artifact's format or tooling prevents drift (e.g., schema validation, type system, generated output) | Lowest |
ci-verified |
CI/CD pipeline checks correctness on every commit | Low |
human-reviewed |
Requires human review to detect drift | Medium |
informational-only |
No enforcement mechanism; drift is expected and tolerated | Highest |
Prefer self-enforcing and ci-verified artifacts. If an artifact can only be human-reviewed or informational-only, document why a stronger mechanism is not feasible.
Required Metadata Block¶
Every new engineering artifact MUST carry this metadata block (YAML frontmatter, inline comment, or structured header — format matches the artifact type):
artifact:
owner: # Who maintains this
consumer: # Who reads/uses this (MUST be specific — see Valid Consumers)
purpose: # Why this exists (one sentence)
lifetime: # permanent | until-merged | until-superseded | delete-after-execution
authority: # Which system owns this knowledge long-term
replaces: # What this supersedes (or "none")
enforcement: # self-enforcing | ci-verified | human-reviewed | informational-only
If any field cannot be filled, the artifact MUST NOT be created.
Three Questions Every Artifact Must Answer¶
Before creating any artifact, the author (human or agent) MUST answer:
- Who consumes this? — Name a specific role, system, or pipeline. "Someone might need it" is not an answer.
- What decision or process depends on it? — If nothing breaks when this artifact disappears, it should not exist.
- How is it kept correct? — Name the enforcement mechanism. If the answer is "hope," reconsider creating it.
If any question cannot be answered concretely, the artifact MUST NOT be created.
Valid Consumers¶
- CI pipeline
- Runtime
- Blu CLI / OpenClaw
- A repository
- BluCity-Docs
- GitLab (issues, MR comments, resolved threads)
- A human reviewer with a named role
Invalid Consumer¶
"The agent wanted somewhere to put its thoughts."
If the consumer is the agent itself, the artifact MUST NOT be created.
Examples¶
| Artifact | Owner | Consumer | Lifetime | Authority | Enforcement |
|---|---|---|---|---|---|
| Engineering Standard | BluCity-Docs | Humans + agents | Permanent | BluCity-Docs | human-reviewed |
| PROJECT.md | Repository | Agents | Permanent | Repository | human-reviewed |
| MR comment | GitLab | Reviewers | Until merged | GitLab | informational-only |
| CI log | GitLab | Engineers | Until superseded | GitLab | self-enforcing |
| Triage report | Operator | Temporary | Delete after execution | GitLab issues/comments | informational-only |
| JSON Schema | Repository | Runtime + CI | Permanent | Repository | self-enforcing |
| Pipeline config | GitLab CI | CI pipeline | Permanent | Repository | ci-verified |
Enforcement¶
Agents MUST NOT create artifacts that cannot fill all four fields. Planning artifacts are temporary and MUST either: 1. Become authoritative documentation 2. Become executable work in GitLab 3. Or be deleted
No document may exist solely to describe work that has not been transferred to its authoritative owner.