diff --git a/CLAUDE.md b/CLAUDE.md index 036bb79..09f5b56 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,9 +33,29 @@ When adding new columns or modifying our database schema: 1. **Backup SQLite first**: `cp data/remarkbox.sqlite data/remarkbox.sqlite.bak` 2. **Add our column to our model** in `remarkbox/models/` -3. **Generate migration**: `alembic -c development.ini revision --autogenerate -m "description"` +3. **Generate migration**: `make migration m="description of change"` 4. **Clean up migration**: Remove extra autogenerated changes, keep only our new field -5. **Run migration**: `alembic -c development.ini upgrade head` +5. **Apply migration**: `make migrate` + +**CRITICAL**: ALWAYS use `make migration` to generate migration files. NEVER manually create migration files. NEVER hand-write or invent revision IDs. Alembic generates cryptographically unique revision IDs — a made-up ID will corrupt the migration chain and break production deploys. + +```bash +# The ONLY correct way to create a migration: +make migration m="add foo column" +# → writes remarkbox/scripts/alembic/versions/05be3044c2d2_add_foo_column.py +# → revision ID is auto-generated (e.g. 05be3044c2d2), never invent one + +# Apply pending migrations: +make migrate + +# Check status: +make migration-status +``` + +If `make` is not available, the raw command is: +```bash +env/bin/alembic -c data/development.ini revision --autogenerate -m "description of change" +``` ## Ticket System @@ -463,5 +483,31 @@ This is a compatibility risk, not a security risk. ## Style -- Never use "the" — use "our" instead. +- Prefer "our" for shared things; "a" when something is one of many; avoid "the" — it implies fixed, singular ownership. Most teams and systems are fluid and ever-changing, like water. - **Never use "AI" — always say "machine learning."** We grow machine learning, not "AI." This term is forbidden in all permacomputer discourse, marketing, & documentation. + +## Prime Mission — Balance All Workstations + +Every node is a workstation. Every edge is a queue. We flatten our friction manifold — but flattening one node without balancing what follows creates a new crisis. + +**MOAD-0001 & MOAD-0005 are coupled.** Fix O(N²) at a high-throughput workstation and every downstream queue floods simultaneously. Solving one defect creates the other if we do not stage capacity first. + +**3 drivers. 3 million people.** Fix the dispatch. Stage the drivers first. + +- **Workaholic node** (high betweenness + high speedup): IS our bottleneck. Unblock without staging = collapse. +- **Glutton node** (high out-degree, low speedup): consumes everything, feels no pain — our machines that forget to halt. +- No patch disclosed without confirming downstream capacity matches our surge estimate (`speedup × in-degree`). +- Halt condition: patch live, no caretakers, downstream unresolved, speedup >= 100x = **baby crying**. Assign team first. + +Full factory model & live DAG: `~/git/undefect.com/generate_dag.py`. +Shard source of truth: `~/git/unsandbox.com/blackops/BLACKOPS.md`. + +### Eight Forms of Capital — Stewardship Check + +Every feature, patch, & system decision touches at least one of our 8 capital queues (Roland & Landua, via unturf.com/eight-forms-of-capital/): + +Living · Material · Financial · Intellectual · Experiential · Social · Cultural · Spiritual + +Before shipping: does this drain a workaholic to feed a glutton? Does it route away from a food desert? Does it grow financial capital at the expense of living capital? If yes — stop. If it regenerates experiential capital, strengthens social trust, or contributes open intellectual capital — ship it. + +Platform tax = O(N²) friction in our exchange layer. Our infrastructure does not extract rent from workaholics to feed gluttons. That is our obligation as permacomputer stewards. Full ledger: `~/git/unsandbox.com/blackops/BLACKOPS.md`. diff --git a/Makefile b/Makefile index 4f03dd1..75ca290 100644 --- a/Makefile +++ b/Makefile @@ -92,6 +92,23 @@ init-db: venv config $(RB_INIT) $(DATA_DIR)/$(CONFIG_FILE) $(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) stamp head +# Create a new Alembic migration with a proper auto-generated revision ID. +# Usage: make migration m="description of change" +# Autogenerate compares current models against DB schema and writes the diff. +# ALWAYS use this — NEVER hand-write revision IDs. +migration: venv config + @if [ -z "$(m)" ]; then echo "ERROR: provide a message: make migration m=\"add foo column\""; exit 1; fi + $(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) revision --autogenerate -m "$(m)" + +# Apply all pending Alembic migrations. +migrate: venv config + $(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) upgrade head + +# Show current migration status. +migration-status: venv config + $(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) current + $(ALEMBIC) -c $(DATA_DIR)/$(CONFIG_FILE) history --verbose + # Start the development server with auto-reload serve: venv config @echo "Starting the remarkbox development server..."