Skip to content

0066 — Doc philosophy compliance (Group N)

Status

Accepted.

Context

Six audit findings on doc-style compliance with ../CONTRIBUTING.md and the doc-philosophy rules (no historical narrative, prescriptive voice, status markers in FEATURES/ only, etc.). Zero critical; pure doc cleanup. Bundling into one ADR for the audit trail; the actual work is small targeted edits.

Decision

D-V1 — Status markers in DATA_MODELS consolidated into "Schema status" sections

Per the doc philosophy, implementation status lives in FEATURES/ only. The 📐 Design-only markers previously scattered through DATA_MODELS/*.md field-level descriptions were violations.

Refactor applied: every per-field 📐 Design-only marker has been removed across DATA_MODELS/. Each affected file gains a top-of-file "Schema status" section consolidating the design-only columns or entities into one bulleted list per file. Field descriptions describe the target schema — code-side readers consult the Schema status section once at the top to identify which columns aren't committed yet, instead of scanning row-by-row.

Files updated: ships.md, stations.md, player.md, galaxy.md, npcs.md, npc-lodging.md, planets.md, gameplay.md. jsonb-schema.md already had an equivalent "Launch-target schemas" callout at its head. pirate-holdings.md and cargo-wrecks.md had body-text markers reframed as inline notes pointing at the Schema status section.

The "Source: … (📐 Design-only)" annotations on model files that don't yet exist are reframed as "Source: … (target path — does not yet exist)" — describes the same thing without using a status marker as a code-reference convention.

Going forward: new doc work in DATA_MODELS/ adds entries to the file's Schema status section instead of inline 📐 markers. New columns / entities default to the Schema status list until they're committed; once committed, the entry moves out of the section (or the section shrinks to empty for that file).

D-G1 — FEATURES subdirectory READMEs

Add README.md indexes in:

  • FEATURES/economy/README.md
  • FEATURES/galaxy/README.md
  • FEATURES/gameplay/README.md
  • FEATURES/planets/README.md

Each indexes the docs in its directory with a one-line description per doc. Pattern matches the existing FEATURES/README.md and other directory-level indexes.

D-G2 + D-X1 — Galactic Citizen in GLOSSARY

GLOSSARY.md gains an entry under ## G:

Galactic Citizen — $5/month subscription tier. Unlocks cross-region travel via the natural Nexus warp (per ADR-0043) and standard ARIA features within tier-appropriate cost caps. Free-tier players are confined to their home region; Region Owner ($25/mo) is a strict superset. See OPERATIONS/monetization.md. (Live links resolve from GLOSSARY.md at the repo root, not from this ADR.)

D-X1 collapses into D-G2 — same fix.

D-W1 — Hedging language in bang-import-pipeline.md

Two instances of "may" identified by the audit:

  1. Line 409: "Stations may carry stock for commodities they neither buy nor sell" — prescriptive rewrite: "Stations carry stock for commodities they neither buy nor sell when the catalog defaults reflect typical free-market presence."
  2. Line 488: "any additional CLASS_0 ports the bang payload may contain" — prescriptive rewrite: "any additional CLASS_0 ports the bang payload contains."

Doc voice converges to prescriptive present tense; no behavioral change.

D-S1 — Filename casing convention

CONTRIBUTING.md already specifies "lowercase-with-hyphens" for files. The exception class — top-level reference docs in ALL_CAPS (CLAUDE.md, CONTRIBUTING.md, GLOSSARY.md, README.md, AISPEC.md, FINDINGS.md, MEMORY.md) — is implicit. Add an explicit rule:

Top-level reference docs use ALL_CAPS.md — CLAUDE.md, CONTRIBUTING.md, GLOSSARY.md, README.md, AISPEC.md, FINDINGS.md. These sit at the repo root or as section indexes and are loaded as primary navigation. All other docs (content, system specs, feature pages, ADRs) use lowercase-with-hyphens.md.

tags.md is a build-system artifact (mkdocs-material tag index) and follows lowercase-with-hyphens — it isn't a hand-edited reference doc.

This makes the implicit convention explicit and removes ambiguity.

Consequences

  • Four new README.md files in FEATURES subdirs. Each is short (one-line per doc); maintenance cost is low (new docs in the subdir get a one-line entry added to the README).
  • GLOSSARY entry for Galactic Citizen closes a known gap; the term appears elsewhere in the docs without a glossary backing.
  • Two prescriptive-voice edits in bang-import-pipeline.md — no behavioural meaning change.
  • CONTRIBUTING.md filename rule clarifies the implicit ALL_CAPS / lowercase split.
  • DATA_MODELS status-marker refactor applied. 69 inline 📐 Design-only markers removed across 8 files; each file gains a "Schema status" section at the top listing design-only columns / entities. Field descriptions are now pure target-schema specs.

Alternatives considered

  • Defer the DATA_MODELS status-marker refactor (D-V1). Was the initial framing in this ADR; the refactor is now done. The "this is too much surface area" objection didn't hold up — sed-based bulk removal plus per-file Schema status section additions completed inside the same audit-resolution batch.
  • Renaming tags.md to TAGS.md to align with the ALL_CAPS top-level reference convention (D-S1). Rejected — tags.md is a build artifact, not a hand-edited reference doc; the lowercase name correctly signals that.