---
id: naming-convention
title: Naming Convention
module: substrate
cluster: Substrate
type: spec
version: v0.2.1
status: Draft
tier: free
contract_role: ""
canonical_url: "https://grow.goodcombinator.ai/library/registry/naming-convention"
download_url: "https://grow.goodcombinator.ai/library/registry/naming-convention.md"
license: CC-BY-4.0 (proposed — owner confirmation required)
source: GROW by Good Combinator
retrieved_at: 2026-05-29
---

# Naming Convention

Path layout and naming are load-bearing: tooling, evaluation gates, and cross-cluster references resolve artifacts by path alone. Deviations break the registry. This spec is binding for every file under `/grow/`.

## Path Pattern

```
/grow/<cluster>/<course-id>/<artifact-slug>.md
```

- `<cluster>` — one of `systems`, `execution`, `trust`, `coordination`, `substrate`. Lowercase. Matches the `cluster` frontmatter field.
- `<course-id>` — for cluster artifacts, the kebab-case course identifier carrying the leading **cluster-letter + course-number prefix**: `s1-agent-reliability`, `s2-evaluation-auditability`, `s3-data-provenance` (systems); `e4-workflow-modeling`, `e5-sensor-fusion-data-ops`, `e6-compute-economics` (execution); `t7-govtech-compliance`, `t8-security-zero-trust` (trust); `c9-dao-governance`, `c10-commercialization-architecture` (coordination). The prefix tracks the **course number**, not the module ID — Compute Economics is `e6-*` even though its module is `S7`. For substrate, the segment is omitted (substrate files live at `/grow/substrate/<slug>.md`).
- `<artifact-slug>` — kebab-case, identical to the `id` field in frontmatter. No date stamps, no version suffixes, no author initials.

## Slug Rules

1. Lowercase ASCII letters, digits, hyphens only. No underscores, spaces, dots (except the `.md` extension), or capitals.
2. Hyphens separate words; no doubled hyphens.
3. Slug starts with a letter, ends with a letter or digit.
4. Length: 3–60 characters.
5. Slug equals filename equals frontmatter `id`. All three must match exactly.

## One Artifact Per File

Every `.md` file contains exactly one artifact. Registers with many rows are still a single artifact. Bundles, indices, or "appendix" files are forbidden — split into separate artifacts and wire them via `upstream_deps` / `downstream_consumers`.

## Forbidden Patterns

- Capitalized or CamelCase slugs (`FailureModeRegister.md`).
- Underscores or spaces (`failure_mode_register.md`, `failure mode register.md`).
- Version, date, or author suffixes (`failure-mode-register-v2.md`, `failure-mode-register-2026-05.md`, `failure-mode-register-dl.md`).
- Numeric prefixes for ordering (`01-failure-mode-register.md`). Ordering is established by `upstream_deps`, not by lexical sort.
- Nested directories below `<course-id>` (`/grow/systems/s1-agent-reliability/registers/failure-mode-register.md`). The course directory is flat.
- Plural directory names (`/grow/systems/courses/…`).
- Markdown filenames without the `.md` extension, or with `.markdown`.
- Multiple artifacts in one file separated by `---`.
- Files that live outside `/grow/` and claim membership via frontmatter alone.

## Worked Examples

**Example 1 — Systems / S1 / register.**
Artifact: failure mode register for Agent Reliability.
Path: `/grow/systems/s1-agent-reliability/s1-failure-mode-register.md`
Frontmatter `id`: `s1-failure-mode-register`. Module `S1`, cluster `systems`.

**Example 2 — Systems / S2 / matrix.**
Artifact: evaluation test seed matrix that derives from S1's failure modes.
Path: `/grow/systems/s2-evaluation-auditability/s2-eval-test-seed-matrix.md`
Frontmatter `id`: `s2-eval-test-seed-matrix`. `upstream_deps` includes `s1-failure-mode-register`. Module `S2`, cluster `systems`.

**Example 3 — Substrate / schema.**
Artifact: the shared frontmatter schema itself.
Path: `/grow/substrate/shared-artifact-schema.md`
Frontmatter `id`: `shared-artifact-schema`. Module and course both `substrate`, cluster `substrate`.

**Example 4 — Execution / Course 6 / policy (module ≠ course).**
Artifact: the routing policy for Compute Economics.
Path: `/grow/execution/e6-compute-economics/e6-routing-policy.md`
Frontmatter `id`: `e6-routing-policy`. `course: 6`, `cluster: execution`, `module: S7`. The `e6` prefix encodes the course number (6), and the cluster directory (`execution`) is determined by the course number, not by the module ID. This is the canonical example of why the prefix tracks course, not module.

**Example 5 — Coordination / Course 10.**
Artifact: the commercialization package templates.
Path: `/grow/coordination/c10-commercialization-architecture/c10-commercialization-package.md`
Frontmatter `id`: `c10-commercialization-package`. `course: 10`, `cluster: coordination`, `module: S10`. Two-digit course numbers keep the prefix (`c10`).

## Enforcement

The builders evaluation gate (a) walks `/grow/`, (b) asserts every file matches the pattern and slug rules, (c) opens each file and confirms filename == `id` == slug-segment, (d) confirms cluster directory matches the `cluster` field. Any mismatch fails Existence and Versioning checks and blocks ship.