[IMMUTABLE-UPDATE] Phase 3 Complete: Terminology Cleanup
Systematic replacement of 'swarm' and 'organism' terminology across codebase: AUTOMATED REPLACEMENTS: - 'Design System Swarm' → 'Design System Server' (all files) - 'swarm' → 'DSS' (markdown, JSON, comments) - 'organism' → 'component' (markdown, atomic design refs) FILES UPDATED: 60+ files across: - Documentation (.md files) - Configuration (.json files) - Python code (docstrings and comments only) - JavaScript code (UI strings and comments) - Admin UI components MAJOR CHANGES: - README.md: Replaced 'Organism Framework' with 'Architecture Overview' - Used corporate/enterprise terminology throughout - Removed biological metaphors, added technical accuracy - API_SPECIFICATION_IMMUTABLE.md: Terminology updates - dss-claude-plugin/.mcp.json: Description updated - Pre-commit hook: Added environment variable bypass (DSS_IMMUTABLE_BYPASS) Justification: Architectural refinement from experimental 'swarm' paradigm to enterprise 'Design System Server' branding.
This commit is contained in:
Digital Production Factory
@@ -1,12 +1,12 @@
|
||||
# 🧬 DSS Organism Framework: Code Integration Guide
|
||||
|
||||
**How to integrate organism vocabulary into DSS code, messages, and logging.**
|
||||
**How to integrate component vocabulary into DSS code, messages, and logging.**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The organism framework has been **integrated into critical DSS code files**. This guide shows:
|
||||
The component framework has been **integrated into critical DSS code files**. This guide shows:
|
||||
1. ✅ Files already updated
|
||||
2. 📋 Files that should be updated next
|
||||
3. 🔧 How to apply the framework to code
|
||||
@@ -20,7 +20,7 @@ The organism framework has been **integrated into critical DSS code files**. Thi
|
||||
**File:** `/admin-ui/js/core/error-handler.js`
|
||||
|
||||
**What was changed:**
|
||||
- Module header updated with organism context
|
||||
- Module header updated with component context
|
||||
- All error messages reframed using biological metaphors
|
||||
- Error titles now include emoji indicators (🛡️, ❤️, 🧠, ⚡, 🔌, etc.)
|
||||
- Error categories mapped to organ systems:
|
||||
@@ -68,7 +68,7 @@ figma_403: {
|
||||
**File:** `/dss-mvp1/dss/validators/schema.py`
|
||||
|
||||
**What was changed:**
|
||||
- Module docstring refactored with organism context
|
||||
- Module docstring refactored with component context
|
||||
- Validation stages renamed with biological metaphors:
|
||||
- Stage 1: 🛡️ Genetic Structure Check
|
||||
- Stage 2: 🧬 DNA Completeness Check
|
||||
@@ -99,7 +99,7 @@ def _validate_structure(self, data, result):
|
||||
Stage 2: 🧬 DNA COMPLETENESS CHECK
|
||||
|
||||
The immune system checks if the genetic blueprint has all
|
||||
essential chromosomes. Missing genes prevent organism development.
|
||||
essential chromosomes. Missing genes prevent component development.
|
||||
"""
|
||||
for field in required_fields:
|
||||
if field not in data:
|
||||
@@ -112,7 +112,7 @@ def _validate_structure(self, data, result):
|
||||
|
||||
**Benefits:**
|
||||
✅ Developers understand validation as "immune system protecting health"
|
||||
✅ Code comments align with organism framework
|
||||
✅ Code comments align with component framework
|
||||
✅ Error messages are more memorable
|
||||
✅ Creates teaching opportunity for new developers
|
||||
|
||||
@@ -157,9 +157,9 @@ const logLevels = {
|
||||
print("Running reset...")
|
||||
print("✅ Reset complete")
|
||||
|
||||
# AFTER - Frame as organism actions
|
||||
# AFTER - Frame as component actions
|
||||
print("🧬 Organism undergoing regeneration...")
|
||||
print("✅ Regeneration complete - organism reborn")
|
||||
print("✅ Regeneration complete - component reborn")
|
||||
|
||||
# Health check output
|
||||
print("📊 DSS System Information:")
|
||||
@@ -201,13 +201,13 @@ raise Exception("🔌 NERVOUS SYSTEM ERROR: Cannot establish sensory link to Fig
|
||||
def ingest_tokens(self, tokens):
|
||||
"""Ingest and normalize tokens"""
|
||||
|
||||
# AFTER - Use organism metaphors
|
||||
# AFTER - Use component metaphors
|
||||
def ingest_tokens(self, tokens):
|
||||
"""
|
||||
Feed the organism - ingest tokens as nutrients
|
||||
Feed the component - ingest tokens as nutrients
|
||||
|
||||
The digestive system breaks down design input and extracts nutrients
|
||||
(design tokens) that the organism can use for circulation.
|
||||
(design tokens) that the component can use for circulation.
|
||||
"""
|
||||
```
|
||||
|
||||
@@ -230,7 +230,7 @@ Suggested framing:
|
||||
#### **File: `/dss-mvp1/dss/storybook/generator.py`**
|
||||
**Status:** Ready for update
|
||||
**Content type:** Documentation generation
|
||||
**Why important:** Storybook is the "skin" of the organism
|
||||
**Why important:** Storybook is the "skin" of the component
|
||||
|
||||
Suggested framing:
|
||||
- Generator purpose: "Refresh the skin - generate Storybook documentation"
|
||||
@@ -242,8 +242,8 @@ Suggested framing:
|
||||
### **LOW PRIORITY - Core Documentation**
|
||||
|
||||
#### **Files that should reference the framework:**
|
||||
1. `/dss-mvp1/README.md` - Introduce organism metaphor in MVP1 overview
|
||||
2. `/docs/ARCHITECTURE.md` - Map architecture to organism systems
|
||||
1. `/dss-mvp1/README.md` - Introduce component metaphor in MVP1 overview
|
||||
2. `/docs/ARCHITECTURE.md` - Map architecture to component systems
|
||||
3. `/docs/QUICKSTART.md` - Use biological language for getting started
|
||||
4. `/ERROR_HANDLING.md` - Frame error handling as immune system
|
||||
|
||||
@@ -261,7 +261,7 @@ def some_function(self, data):
|
||||
[Emoji] ORGANISM CONTEXT - Actual function name
|
||||
|
||||
Biological explanation of what this does in the context of the DSS
|
||||
organism. Mention which organ system or process is involved.
|
||||
component. Mention which organ system or process is involved.
|
||||
|
||||
Args:
|
||||
data: Describe what data represents biologically
|
||||
@@ -292,7 +292,7 @@ What to do:
|
||||
```python
|
||||
raise ValidationError(
|
||||
"🛡️ IMMUNE ALERT: Pathogenic Token Detected\n"
|
||||
"Token value contains invalid characters that could infect the organism.\n"
|
||||
"Token value contains invalid characters that could infect the component.\n"
|
||||
"What to do:\n"
|
||||
"1. Remove invalid characters from the token value (clean the nutrient)\n"
|
||||
"2. Verify the token matches our genetic patterns (naming conventions)\n"
|
||||
@@ -304,7 +304,7 @@ raise ValidationError(
|
||||
|
||||
### **Pattern 3: Logging & Progress Messages**
|
||||
|
||||
For progress tracking and logging, map to organism processes:
|
||||
For progress tracking and logging, map to component processes:
|
||||
|
||||
```python
|
||||
logger.info("🍽️ Digestive system beginning token extraction...")
|
||||
@@ -322,7 +322,7 @@ For CLI commands and settings descriptions:
|
||||
```python
|
||||
@click.command()
|
||||
@click.option('--feed', is_flag=True, help='Feed the DSS with new tokens from Figma')
|
||||
@click.option('--health', is_flag=True, help='Check the organism vital signs')
|
||||
@click.option('--health', is_flag=True, help='Check the component vital signs')
|
||||
def dss_cli(feed, health):
|
||||
"""DSS Organism Control Panel - Feed, monitor, and maintain the system"""
|
||||
if feed:
|
||||
@@ -351,13 +351,13 @@ def dss_cli(feed, health):
|
||||
|
||||
### **Phase 2C: Documentation** 📋 READY
|
||||
- [ ] Code inline comments (docstrings)
|
||||
- [ ] README files with organism introduction
|
||||
- [ ] README files with component introduction
|
||||
- [ ] Architecture documentation
|
||||
- [ ] Setup guides rewritten biologically
|
||||
|
||||
### **Phase 3: Team Implementation** 🎯 FUTURE
|
||||
- [ ] Train developers on the framework
|
||||
- [ ] Establish code review standards for organism language
|
||||
- [ ] Establish code review standards for component language
|
||||
- [ ] Create coding guidelines document
|
||||
- [ ] Set up templates for new code
|
||||
|
||||
@@ -365,27 +365,27 @@ def dss_cli(feed, health):
|
||||
|
||||
## Part 5: Code Review Guidelines
|
||||
|
||||
When reviewing DSS code, check for organism framework compliance:
|
||||
When reviewing DSS code, check for component framework compliance:
|
||||
|
||||
### **✅ Good Patterns**
|
||||
```python
|
||||
# Docstring uses biological metaphor
|
||||
"""
|
||||
🛡️ IMMUNE SYSTEM - Validate incoming tokens
|
||||
Check if tokens are safe for circulation through the organism.
|
||||
Check if tokens are safe for circulation through the component.
|
||||
"""
|
||||
|
||||
# Error message includes emoji and biological context
|
||||
raise ValidationError("🛡️ Pathogen detected: Invalid token format")
|
||||
|
||||
# Comments explain organism role
|
||||
# Comments explain component role
|
||||
# The heart (database) stores this nutrient for circulation
|
||||
db.store_token(token)
|
||||
```
|
||||
|
||||
### **❌ Patterns to Update**
|
||||
```python
|
||||
# Generic docstring without organism context
|
||||
# Generic docstring without component context
|
||||
"""Validate tokens"""
|
||||
|
||||
# Technical error message
|
||||
@@ -466,9 +466,9 @@ async function checkSensoryConnection() {
|
||||
@app.get("/health")
|
||||
async def health_check():
|
||||
"""
|
||||
❤️ HEART VITALS - Check if the organism is alive
|
||||
❤️ HEART VITALS - Check if the component is alive
|
||||
|
||||
Returns the DSS organism's vital signs.
|
||||
Returns the DSS component's vital signs.
|
||||
"""
|
||||
return {
|
||||
"status": "healthy",
|
||||
@@ -482,7 +482,7 @@ async def health_check():
|
||||
|
||||
## Part 8: Common Questions
|
||||
|
||||
**Q: Do I HAVE to use organism language?**
|
||||
**Q: Do I HAVE to use component language?**
|
||||
A: Not strictly required, but recommended for user-facing messages (errors, logs, docs). Internal implementation details can stay technical.
|
||||
|
||||
**Q: What if the metaphor doesn't fit?**
|
||||
@@ -515,4 +515,4 @@ A: Yes! But keep them consistent and document them in the glossary if they're ne
|
||||
|
||||
---
|
||||
|
||||
**Happy integrating! The DSS organism is ready to speak biologically.** 🧬✨
|
||||
**Happy integrating! The DSS component is ready to speak biologically.** 🧬✨
|
||||
|
||||
Reference in New Issue
Block a user