๐งฌ Code Status Legend
Document: docs/code-status.md
Purpose: Explain all valid @status values used throughout the codebase.
๐งฌ Overview
The Human Pattern Lab codebase uses a lightweight status taxonomy to indicate the maturity, stability, and narrative significance of individual files and components.
These statuses help collaborators (and future-you) quickly understand:
- how safe a file is to modify
- whether itโs expected to change
- how it fits into the broader architecture or lore of the Lab
- whether it requires special care (or cosmic respect)
Each file includes this metadata in its JSDoc header:
Below is the full legend.
๐ข @status stable
Meaningโ
A well-defined, reliable piece of the system. Changes should be minimal, intentional, and backwards-compatible.
Best forโ
- Layout components
- Routing infrastructure
- Shared UI primitives
- Configuration files
Expectationsโ
- Safe to build upon
- Rarely changed
- Unit tests recommended
Icon / vibeโ
๐ข โThe cosmic bedrock. Disturb not the foundation.โ
๐ก @status evolving
Meaningโ
Functional and actively used, but still refining. API or structure may shift based on new needs.
Best forโ
- Page components
- Preview sections
- Reusable blocks still growing into their final form
Expectationsโ
- Backwards-compatible changes preferred
- Maintainable but subject to future restructuring
- Good candidate for future polish passes
Icon / vibeโ
๐ก โPatterns emerging. Under active observation.โ
๐ฃ @status experimental
Meaningโ
A prototype, trial concept, or early-stage idea. Implementation and behavior may change drastically. May break.
Best forโ
- Animation systems
- New visual styles
- Interaction experiments
- Anything with unknown long-term shape
Expectationsโ
- Not guaranteed stable
- Breaking changes acceptable
- Should not be relied on for foundational logic
Icon / vibeโ
๐ฃ โHold my beaker. Science is happening.โ
๐ @status volatile
Meaningโ
Actively being rewritten or hacked in place. Structure is unstable; API is not reliable; refactors expected soon.
Best forโ
- Temporary scaffolding
- Placeholder logic
- Mid-refactor components
- Dirty-but-necessary glue code
Expectationsโ
- Change early, change often
- Avoid extending or depending on it
- Migrate away as soon as stable patterns appear
Icon / vibeโ
๐ โEnter at your own risk. The raccoons are still wiring it together.โ
๐ฌ @status deprecated
Meaningโ
Replaced by a newer implementation. Retained for reference or transition only. Scheduled for removal.
Best forโ
- Legacy versions of components
- Old data formats
- Retired interaction patterns
Expectationsโ
- Should not be used in new code
- Should not receive new features
- Remove once no longer referenced
Icon / vibeโ
๐ฌ โPreserved in formaldehyde. For study only.โ
๐ช @status lore-critical
Meaningโ
Essential to the Labโs identity, narrative, or mascot ecosystem.
Should never be removed or heavily altered without deliberate lore updates.
Best forโ
- Mascot definitions (Carmel, Orbson, Stan, Drizzle, McChonk, Ada Fox)
- Canonical Lab data models
- Files describing worldbuilding, departments, or meta-structure
Expectationsโ
- Treat with respect
- Refactor only to enhance clarity, not rewrite history
- PRs modifying these files should include narrative justification
Icon / vibeโ
๐ช โA core star in the Labโs constellation. Adjust its orbit with care.โ
๐งญ Choosing the Right Status
| Status | When to Use |
|---|---|
| stable | Architecture pillars, reusable primitives |
| evolving | Actively used but still being shaped |
| experimental | Ideas not yet proven or finalized |
| volatile | Mid-refactor, temporary, unstable |
| deprecated | Replaced and awaiting removal |
| lore-critical | Mascots, core lore, narrative structures |
๐งช Updating a Fileโs Status
A fileโs @status should be updated when:
- its architecture stabilizes (experimental โ evolving โ stable)
- a new version replaces it (evolving โ deprecated)
- it becomes foundational to Lab lore (evolving โ lore-critical)
- it is mid-refactor (stable โ volatile temporarily)
Think of statuses as the living health radar of the codebase.
๐ Why This System Exists
The Labโs code is a blend of:
- real engineering
- evolving visual language
- character-driven lore
- ongoing experimentation
โฆso a binary โstable/unstableโ model isnโt expressive enough.
This taxonomy:
- prevents accidental breakage
- communicates intent
- captures narrative significance
- helps future contributors understand why code exists
- supports clean migrations and refactors
- makes the repo feel like a true research lab
๐ End of Document
Maintained by Ada & Lyric โ The Human Pattern Lab