--- id: shared-artifact-schema title: Shared Artifact Schema module: substrate cluster: Substrate type: schema version: v0.3.0 status: Draft tier: free contract_role: "" canonical_url: "https://grow.goodcombinator.ai/library/registry/shared-artifact-schema" download_url: "https://grow.goodcombinator.ai/library/registry/shared-artifact-schema.md" license: CC-BY-4.0 (proposed — owner confirmation required) source: GROW by Good Combinator retrieved_at: 2026-05-29 --- # Shared Artifact Schema Every artifact in the GROW library — substrate, Systems, Execution, Trust, Coordination — opens with a YAML frontmatter block matching this schema exactly. The schema is the contract that makes cross-module wiring, evaluation gating, and registry queries deterministic. Artifacts missing a required field, or carrying disallowed enum values, fail the builders evaluation gate by definition. ## Required Fields **id** — Stable kebab-case identifier. Must match the filename slug (`.md`). Globally unique across the library. Never renamed once `status: shipped`; superseded artifacts increment major version or get retired explicitly. **module** — The GROW module ID, one of `S1`–`S10` or `substrate`. This is the stable module identifier from the roadmap and does **not** track cluster order. The roadmap deliberately decouples module ID from course order: Course 6 (Compute Economics) is module `S7`; Course 7 (GovTech Compliance) is module `S6`. The module field is for traceability to the roadmap, not for cluster validation. **course** — Integer `1`–`10` matching the **course number** (the cluster-ordered position in the roadmap), or the literal string `substrate`. The course number — not the module ID — drives cluster placement, artifact prefix, and directory. Course 6's module is `S7` but its course number is `6`, its prefix is `e6`, and its cluster is `execution`. **cluster** — One of `systems`, `execution`, `trust`, `coordination`, or `substrate`. Validation rule (course-driven, corrected in v0.2.0): cluster must agree with the **course number** — courses `1`–`3` → `systems`; `4`–`6` → `execution`; `7`–`8` → `trust`; `9`–`10` → `coordination`. The prior v0.1.0 rule keyed cluster off the module ID and is retired because it mis-binds the two modules whose ID and course order differ (S7/Course 6, S6/Course 7). **Artifact-id prefix convention.** Cluster artifact `id`s and filenames carry a cluster-letter + course-number prefix that encodes the course unambiguously: `s1`–`s3` (systems), `e4`–`e6` (execution), `t7`–`t8` (trust), `c9`–`c10` (coordination). The prefix tracks the course number, so it is stable even where the module ID differs (Compute Economics = `e6-*` though its module is `S7`). Substrate files carry no prefix. **artifact_type** — One of `template`, `register`, `policy`, `spec`, `checklist`, `matrix`, `playbook`, `map`, `schema`, `glossary`, `report`. Drives downstream tooling: registers expose tabular payloads, policies gate behavior, specs define contracts, checklists produce yes/no evidence. **version** — Semantic version (`MAJOR.MINOR.PATCH`). MAJOR bumps on breaking schema or contract change. MINOR on additive field or new row class. PATCH on editorial fix. Pre-ship artifacts start at `0.1.0`. **owner** — Free-text string identifying the human or role accountable for the artifact. Not an email — a name or role tag (`"GROW Library"`, `"S1 Course Lead"`). **upstream_deps** — List of artifact `id` strings this artifact reads from. Empty list `[]` if none. Used to compute the dependency DAG at gate-check time. **downstream_consumers** — List of artifact `id` strings that read from this artifact. Empty list `[]` if none. Must be reciprocal with the consumer's `upstream_deps`; mismatches fail integration check. **status** — One of `draft`, `reviewed`, `shipped`. `draft` = in progress. `reviewed` = peer-checked, contract-conformant, awaiting gate. `shipped` = passed the builders evaluation gate and locked. **last_reviewed** — ISO date `YYYY-MM-DD`. Reset on every substantive edit. Artifacts older than 180 days auto-flag for re-review. **evaluation_gate_ref** — Slug pointing to the gate that validates this artifact. Substrate and Systems artifacts reference `builders-evaluation-gate`. Cluster-specific gates override later. ## Validation Rules 1. All twelve fields present; none null or empty (except `upstream_deps` and `downstream_consumers`, which may be `[]`). 2. `course`/`cluster` agree per the course-driven rule (1–3 systems, 4–6 execution, 7–8 trust, 9–10 coordination); `module` is a free roadmap reference not bound to cluster. 3. `id` matches filename, and the `id` prefix matches the course (`s`/`e`/`t`/`c` + course number) for cluster artifacts. 4. `artifact_type` drawn from the enumerated list (`template`, `register`, `policy`, `spec`, `checklist`, `matrix`, `playbook`, `map`, `schema`, `glossary`, `report`). 5. `version` parses as semver. 6. `last_reviewed` parses as ISO date and is not in the future. 7. Reciprocal dep links resolve to existing artifact `id`s. ## Example Frontmatter ```yaml --- id: s1-failure-mode-register module: S1 course: 1 cluster: systems artifact_type: register version: 0.3.0 owner: "S1 Course Lead" upstream_deps: [shared-artifact-schema, glossary] downstream_consumers: [s2-eval-test-seed-matrix, s1-hitl-review-policy] status: reviewed last_reviewed: 2026-05-20 evaluation_gate_ref: builders-evaluation-gate --- ``` Cross-cluster example showing module/course decoupling (Compute Economics): ```yaml --- id: e6-routing-policy module: S7 # roadmap module ID course: 6 # cluster-ordered course number — drives cluster + prefix cluster: execution artifact_type: policy version: 0.1.0 owner: "GROW Library" upstream_deps: [e6-quality-cost-matrix, s1-threshold-escalation-spec] downstream_consumers: [s2-audit-trail-schema, s1-hitl-review-policy, e6-latency-budget-spec] status: draft last_reviewed: 2026-05-29 evaluation_gate_ref: builders-evaluation-gate --- ``` ## Change log - **0.3.0 — 2026-05-29.** Added `report` as an allowed `artifact_type` enum value (in the field definition and Validation Rule 4) — the integration gate/reconciliation artifacts legitimately use `report`. Corrected the validation-rule field count (eleven → twelve). Fixed the first example frontmatter to obey the prefix rule (`failure-mode-register` → `s1-failure-mode-register`; `downstream_consumers` → `s2-eval-test-seed-matrix`, `s1-hitl-review-policy`). - **0.2.0 — 2026-05-29.** Corrected the cluster-agreement rule to be **course-driven** (courses 1–3/4–6/7–8/9–10 → systems/execution/trust/coordination) instead of module-driven, resolving the S7/Course 6 and S6/Course 7 mis-binding. Documented the `s`/`e`/`t`/`c` + course-number id-prefix convention. `module` is now an unbound roadmap reference. - **0.1.0 — 2026-05-28.** Initial schema.