# GCS-NAME-001 - Naming and Structure Contract

Spec ID      : GCS-NAME-001
Title        : Naming and Structure
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-SYS-001
Supersedes   : -

## 1. Principle

A name is correct only if it is derivable from this contract. No code,
contract, folder, API key, environment variable, container, queue, database
object, class, function, or display label may coin a local synonym.

Every concept has one canonical `snake_case` vocabulary row in
GCS-NAME-002. Other spellings are mechanical casing transforms of that row.

## 2. Casing Forms

| Form | Rule | Used for | Example |
| --- | --- | --- | --- |
| `snake_case` | lowercase words joined by underscore | Python modules/functions, SQL tables/columns, Markdown file slug bodies | `control_topology` |
| `PascalCase` | capitalized words, no separators | Python classes, TypeScript types, React components | `ControlTopology` |
| `camelCase` | first word lower, subsequent words capitalized | JSON wire keys, TypeScript variables/props | `controlTopology` |
| `SCREAMING_SNAKE` | uppercase snake | constants, env vars, closed enum members | `GCS_ENV` |
| `kebab-case` | lowercase words joined by hyphen | URL paths, Docker services/DNS names, CSS classes | `gcs-web` |
| `Title Case` | words separated by spaces | UI labels and document headings | `Control Topology` |

Wire keys are `camelCase` and must be produced by serialization, not
hand-spelled independently from Python/database `snake_case` names.

## 3. Contract Artifact Naming

Contract files use:

```text
contracts/GCS-<DOMAIN>-<NNN>_<Title_In_Title_Case_With_Underscores>.md
```

Examples:

- `contracts/GCS-NAME-001_Naming_and_Structure_Contract.md`
- `contracts/GCS-DATA-003_Persistence_Contract.md`

The register and overview are contract artifacts and follow the same ID rule.

## 4. Repository Structure

| Path | Owner | Rule |
| --- | --- | --- |
| `contracts/` | GCS-REGISTER-001 | Binding contract artifacts only |
| `assets/` | GCS-NAME-001 / GCS-SYS-001 | Static visual assets and browser-only figure code |
| `build/` | GCS-SYS-001 / GCS-SIG-003 | Flagship interactive instrument (browser-only; fixture or stamped public data) |
| `tools/` | GCS-TEST-001 | Contract validators and check-mode tools |
| `ops/` | GCS-DEPLOY-001 / GCS-DEPLOY-002 | Runtime templates and operator examples without secrets |
| `.github/workflows/` | GCS-TEST-001 | CI gate wiring |
| `tests/` | GCS-TEST-001 | Future tests that import app code only |
| `app/` | GCS-STACK-001 | Future Python application code, not present in Phase 0 |
| `api/` | GCS-API-001 | Future API route modules, not present in Phase 0 |
| `migrations/` | GCS-DATA-003 | Future DB migrations, not present in Phase 0 |
| `conversations/` | GCS-SYS-001 | Product provenance and charters; non-binding narrative |

The current root `index.html` is the static public study surface. The flagship
interactive instrument lives under `build/` and embeds from the study page.
Future application server code must not be placed at repository root.

## 5. Source File Contract Header

Every source file under implementation paths must begin with a measurable
contract header. The header must contain these exact labels:

```text
Contract refs:
Purpose:
Canonical concepts touched:
Inputs accepted:
Outputs guaranteed:
Positive verification:
Negative verification:
Validation command:
External boundaries:
```

The header is the file-level input -> output promise. Tests assert the promise
at the file or module boundary, not private implementation details.

The current source extensions are `.html`, `.js`, `.py`, `.yml`, and `.yaml`.
Static `.svg` assets are governed as data/visual assets and must be referenced
with descriptive `alt` text where rendered.

## 6. Environment Variables

GCS environment variables use `SCREAMING_SNAKE` and the `GCS_` prefix. Every
variable must appear in `ops/local_variables.example` with a comment. A
`GCS_*` variable not documented there does not exist.

## 7. Forbidden Patterns

The following are contract violations:

- A source file missing any required contract-header label.
- A file, folder, container, queue, env var, route, class, or column whose name
  is not derivable from GCS-NAME-002.
- `app/` importing `tests/`.
- Undocumented `GCS_*` environment variables.
- Code references to queue/broker terms while GCS-RUNTIME-001 forbids queues.
- Active Compose files using `container_name`.

## 8. Validation

Canonical command:

```bash
python3 -m tools.check_contracts --check
```

Positive verification: the command passes when all source headers, registered
contracts, documented env vars, no-queue rule, and inactive-container rules are
conformant.

Negative verification: removing a required header label, adding an undocumented
`GCS_*` variable, or adding a queue token to source code makes the command exit
non-zero with file and line evidence.