🛠️ DEVELOPER NOTES — SmartSTNPro Build Constitution
Rules to observe before every iteration · V100 onwards · L7 FOC Eyes Only
1. 🔐 ROLE INTEGRITY FIRST
Before adding any feature, ask: Who should see this? Who should act? Who should never see this? Never build without assigning it to a level. If visible to the wrong role — the entire accountability chain breaks.
2. 📸 EVERY FINANCIAL OR SAFETY ACTION NEEDS EVIDENCE
If money or fuel moves → photo + reading + timestamp required. No exceptions. Remarks-only is acceptable only for non-financial, non-safety items.
3. 🔢 NO COMPUTATION WITHOUT A COMPLETE READING
Before building any auto-calculation: What is the opening value? What is the closing value? Is there a mid-point (e.g. price change) that splits the computation? If any is missing → block and flag. Never assume or estimate.
4. ⏰ TIMESTAMPS ARE SACRED
Always auto-captured — never user-editable. Always device-time at moment of action. Any entry without a timestamp is considered incomplete.
5. 🚨 FLAG DON'T BLOCK — BUT ALWAYS RECORD
Minor → Toast + logged · Moderate → Badge + flagged in record · High/Critical → WA alert to chain of command.
Never prevent submission — always let TL submit with a flag attached. Operations must continue even during issues, but nothing goes unrecorded.
6. 🔄 EVERY MODULE HAS A CLOSED LOOP
Before building, map the full lifecycle:
Who initiates → Who acts → Who closes → Who verifies → Where does it surface in Turnover/DSR?
A module is not complete until the loop is closed. Open loops create accountability gaps.
7. 📋 SHIFT TURNOVER IS THE FINAL VALIDATOR
Everything logged during a shift must surface in Shift Turnover. If a new feature doesn't appear in turnover — it's invisible to the next TL. Ask: Does this need to appear in turnover summary? Does it affect what the next shift inherits?
8. 🧱 BUILD ON EXISTING PATTERNS — DON'T REINVENT
Established patterns to follow:
· Modals for data entry · Cards for display · Badges for counts/alerts
· SL_ITEMS array for shift log items · TAB_MIN_LEVEL for access control
· localStorage keys → format: he_[module]_[station]_[date]
· L2_ROLE_TABS for role-based tab access
Deviating from these creates inconsistency and hard-to-trace bugs.
9. 💾 DATA MUST BE STATION + DATE + USER SCOPED
Every storage key must include: Station — no data leaks between stations. Date — no data carries over between days unintentionally. User — every record knows who created it.
10. 📱 MOBILE FIRST — ALWAYS
The TL is on the floor with a phone. Every new UI must: work with one thumb, have large tap targets, show critical info above the fold, never require scrolling to find the submit button. Photos must use camera capture unless gallery is intentional (e.g. multi-upload).
11. 🔗 MODULES DON'T EXIST IN ISOLATION
Before building, check: Does this affect Shift Log? Turnover? DSR/Sales? Does it trigger an alert or notification? Does it feed into a variance report? A change in one module can ripple into 3 others. Always trace the connections first.
12. 🧪 THE QUESTION BEFORE EVERY FEATURE
"If this field is left blank or this step is skipped — what breaks downstream?"
If the answer is "a lot" → make it mandatory with validation.
If the answer is "nothing critical" → make it optional with a soft prompt.
13. 🏗️ MODULARITY — THE 5 HOOKS
Every module must be self-contained and clearly separate its responsibilities across 5 hooks. No hook should do another hook's job.
❤️
HEART — Data Layer
Stores and retrieves data. localStorage keys, Supabase read/write. Heart never renders. Heart never computes.
🧠
BRAIN — Logic Layer
Calculations, validations, rules, grace periods, thresholds. Brain never stores. Brain never displays.
🦵
KICK — Action Layer
Submit, save, trigger, confirm. Connects Brain → Heart → Gamma. Kick never renders UI. Kick never does raw calculations.
🐍
TAIL — Render Layer
Displays cards, lists, badges, modals, summaries. Reads from Heart. Tail never saves data. Tail never computes.
⚡
GAMMA — Broadcast Layer
WA alerts, toasts, badges, push notifications. Triggered by Kick. Gamma only broadcasts. Gamma never stores or computes.
⚠️ Rule: If a function is doing two hooks' jobs — it must be split.
✅ Test: Can you label every function in your module as Heart, Brain, Kick, Tail, or Gamma? If not — the module is not properly separated.
14. 🫀 THE BODY RULE — EVERY FEATURE BELONGS TO A BODY PART
Before building anything — identify which body part it belongs to. Nothing is built outside the body.
👤
ED — OWNER
Receives advice · Decides · Instructs the whole body
↕ ORDER / ADVICE
🧠 BRAIN
Collects ALL information · Updates · Assesses · Advises Owner
UPDATE
ASSESS
ADVISE
⚡ GAMMA — SECURITY
Guards everything inside & outside · Alerts Brain
🪝 HOOK — GET CUSTOMER
Acquisition · Entry point · Brings customer in
❤️ HEART — OPERATIONS
Core station work · Shift · Fuel · Cash · Daily functions
🦵 KICK
Barrier · High-level service · Promos · Quality gate
🐍 TAIL
Expansion · Growth · New stations · New services
🪝 Hook → ❤️ Heart → 🦵 Kick → 🐍 Tail
⚡ Gamma monitors all
The Rule:
🪝 Hook — acquires. Never operates.
❤️ Heart — operates. Never expands without authority.
🦵 Kick — serves and protects quality. Never bypasses standards.
🐍 Tail — expands. Never operates core without Heart.
⚡ Gamma — secures everything. Never sleeps. Reports to Brain.
🧠 Brain — collects, assesses, advises. Never decides alone.
👤 Ed — decides and instructs. The body obeys.
🎯 ONE-LINE SUMMARY
"Every feature must know who owns it, what evidence it requires, how it computes, where it surfaces, and what breaks if it's skipped."
🫀 THE BODY RULE
"Before building anything — identify which body part it belongs to. Hook acquires. Heart operates. Kick serves and protects. Tail expands. Gamma secures. Brain advises. Ed decides. Nothing is built outside the body."
15. 🚀 SMP DEPLOYMENT PROTOCOL — NEVER BREAK PRODUCTION
SMP1 🔒 PRODUCTION — SACRED
Live on fuel-ops.com. TLs use this every shift. Never touch directly.
Nothing reaches SMP1 without passing SMP2 + SMP3 fully.
SMP2 🔬 DEVELOPMENT — BUILD · BREAK · FIX
Problem found in SMP1 → identify module → pull that module → fix in isolation → confirm fixed.
Like a car engine: pull the broken part, fix it on the bench, put it back.
SMP3 ✅ BUNDLE & DEPLOY — MERGE · PUSH · GO LIVE
Fixed module passes → bundle back into full HTML → push to GitHub → Netlify deploys.
Deploy window: 2:00 AM – 4:00 AM only. Never mid-shift. Never Friday nights.
BRANCH STRATEGY
main → SMP1 (production · fuel-ops.com)
dev → SMP2 staging (modules being fixed)
feature/vXXX → individual builds (Netlify auto-preview URL)
16. 🗂️ MODULE SECTION MARKERS — EVERY MODULE MUST BE FINDABLE
Every module in the codebase must have a clear section marker block at its start.
This makes every module instantly findable — by any developer, by Claude, by anyone.
No module without a marker. No marker without a contract.
REQUIRED FORMAT:
// ████████████████████████████████████████
// MODULE: [NAME] ([prefix]_)
// ❤️ Heart: [load/save functions]
// 🧠 Brain: [calc/validate functions]
// 🦵 Kick: [submit/trigger functions]
// 🐍 Tail: [render functions]
// ⚡ Gamma: [alert/badge functions]
// Storage: he_[module]_[station]_[date]
// Access: L[X] inputs · L[X]+ views
// Feeds: [downstream modules]
// ████████████████████████████████████████
WHY THIS MATTERS:
· TL reports a problem → identify module → search marker → land exactly there
· Fix only that module → nothing else touched → zero collateral damage
· Feeds list shows what breaks downstream if you change something
· New developer reads marker → knows exactly what the module does and touches
RULE:
If you add a new module — add the marker first, before writing any code.
If you fix a module — verify the marker is accurate before submitting.
The marker IS the contract. If the code drifts from the marker — the marker wins.
17. 🔒 NEVER TOUCH WHAT WASN'T ASKED — LOCKED FEATURES REGISTRY
FOR CLAUDE — SESSION START PROTOCOL:
Step 1 — Read the Locked Features Registry below FIRST.
Step 2 — Ask L7: "What specifically needs to be done this session?"
Step 3 — Work only on what L7 states. Nothing else exists.
· No unsolicited audits
· No "I also found this"
· No cross-checking code against changelog
· Confirmed + tested = untouchable
The test before every change:
"Did L7 ask for this?" — If no → stop. Do not proceed.
FOR L7:
If L7 gives an instruction that would break a LOCKED feature — Claude flags it first.
Flag it → explain it → L7 decides. Final call is always L7's.
SAME GOAL. PROTECT THE BUILD. ALWAYS.
📋 LOCKED FEATURES REGISTRY
Read this before every session. ✅ Locked = confirmed + tested. ⏳ Open = pending. ❌ Broken = known issue.
✅ LOCKED
⏳ OPEN
❌ BROKEN
L1 — GAS ATTENDANT / CASHIER
✅ LOCKED Moto Promo — confirmed V103
⏳ OPEN Mobile photo upload — testing in progress
L2 — TEAM LEADER
✅ LOCKED Stock Alert tab access — confirmed V103
L3 — SUPERVISOR
✅ LOCKED Staff & Attendance — confirmed V103
✅ LOCKED Dipstick — confirmed V103
✅ LOCKED Stock Alert — confirmed V103
✅ LOCKED Delivery Variance — confirmed V103
✅ LOCKED Transfer Variance — confirmed V103
✅ LOCKED CPU vs Sales — confirmed V103
L3 — MAINTENANCE CLERK
✅ LOCKED Staff & Attendance — confirmed V103
✅ LOCKED Contacts — confirmed V103
✅ LOCKED Dipstick — confirmed V103
✅ LOCKED Stock Alert — confirmed V103
✅ LOCKED Delivery Variance — confirmed V103
✅ LOCKED Transfer Variance — confirmed V103
✅ LOCKED CPU vs Sales — confirmed V103
✅ LOCKED Sales Report — confirmed V103
✅ LOCKED Overview — confirmed V103
⏳ OPEN Maintenance tab — needs to be added for L3 Maint Clerk
L4 — HR & ADMIN STAFF
✅ LOCKED Delivery Variance — confirmed V103
✅ LOCKED Transfer Variance — confirmed V103
✅ LOCKED CPU vs Sales — confirmed V103
⏳ OPEN Maintenance tab — needs to be added for L4 HR
Last updated: V105 · 2026-03-24 · By Best / L7 · Next open item: mobile photo upload result pending
19. 🔁 SESSION START PROTOCOL — CLAUDE MUST DO THIS FIRST
Before every session, Claude must:
1. Read the constitution — all 19 rules
2. Read the Locked Features Registry — what is confirmed, what is open
3. State the current version of each active app
4. State open items only — nothing else
5. Ask L7: "What needs to be done this session?"
6. Wait for instruction before touching any code
MID-SESSION RULE:
If Claude is about to do something that violates Rules 1–18 — stop, flag it, correct it. Do not wait for L7 to catch it. Claude catches it first.
THE TEST:
Before every action: "Does this violate any of the 19 rules?"
If yes → stop → flag → wait for L7 decision.
SAME GOAL. PROTECT THE BUILD. ALWAYS.
SmartSTNPro · Build Constitution · 19 Rules · V105 · fuel-ops.com
📦 MODULE REGISTRY
Source of truth for all modules · Hook contracts · Storage keys · Dependencies · V101 onwards
⚠️ RULE BEFORE TOUCHING ANY MODULE:
Read its registry entry. Stay within its hooks. If your change affects another module's storage key or feeds into another module — update the registry first.
5 HOOKS: ❤️ Heart = store/retrieve · 🧠 Brain = calculate/validate · 🦵 Kick = submit/trigger · 🐍 Tail = render/display · ⚡ Gamma = alert/badge/notify
🗓️ MODULARIZATION SCHEDULE — SMP PROTOCOL
V100-1Done✅ Module Registry · Constitution Rules 1-15
V101Done✅ Hook violations fixed · Storage keys renamed · Rule 15-16 added
V102SMP2 — Next⏳ Add section markers to ALL 35 modules in code (Rule 16)
V103SMP2 — FixPull broken module → fix in isolation → test → rebundle
V104SMP3 — DeployBundle → push GitHub → 2-4 AM deploy → SMP1 live
V105+StableFull SMP workflow active. Fix one module. Deploy one module.
⚠️ V101 FIX LIST — Hook Violations
Hook violations (7):
· setEl() — Heart renders → split to Tail
· cmRestoreStationPills() — Heart renders → split to Tail
· gsaCheckAndNotify() — Brain stores → split Heart from Brain
· checkOwnerNotifications() — Brain displays → split Tail from Brain
· dsRenderSalesTable() — Tail computes → move calc to Brain
· wkRenderChart() — Tail computes → move calc to Brain
· gsaSendTelegram() — Kick calculates → move calc to Brain
Storage key naming (4):
· foc_marketing_leads → he_foc_leads
· foc_mkt_new_leads → he_foc_new_leads
· foc_support_tickets → he_support_tickets
· v95_flags → he_flags
📋 MODULE CONTRACTS
📋 Shift Log sl_
❤️ slLoad() slSave() slStorageKey()
🧠 slDipAvg() slIsRestricted()
🦵 slSaveDipSlotCm() slAddCmOnly()
🐍 slRender()
⚡ slUpdateMotoBadge()
Storage: he_sl_[station]_[date]
Access: L2 TL inputs · L3+ views · L4+ can unlock
Feeds into: Turnover · DSR · Variance · Sales Report
Status: ✅ Stable · Photos: label+input pattern
📏 Dipstick ds_
❤️ dsGetData() dsStoreReading()
🧠 dsCalcTank() dsCalcTankQuiet() dsVarianceClass()
🦵 dsSubmit()
🐍 dsBuildUI() dsRenderStationVariance()
⚡ dsBuildAlerts()
Storage: he_ds_[station]_[date]
Access: L2 TL entry · L4+ audit view
Feeds into: Sales Report · Inventory · Variance · Turnover
Status: ✅ Stable · CM-only entry added · Photo per reading
🧪 Water Test wt_
❤️ he_wt_photos · he_wt_[station]_[date]
🧠 — (add validation V101)
🦵 wtSubmit()
🐍 wtRenderTanks()
⚡ — (add badge V101)
Storage: he_wt_[station]_[date] · he_wt_photos
Access: L2 TL · L3+ view
Feeds into: Maintenance · Incident Log
Status: ⚠️ Brain hook missing — V101 add result validation
👷 Attendance sf_
❤️ sfGetRoster() sfSaveRoster() he_attendance_
🧠 sfCalcHours() sfCheckBudgetAlerts() v95CheckAttendance()
🦵 sfSubmit()
🐍 sfRenderRoster()
⚡ sfCheckBudgetAlerts()
Storage: he_attendance_[station]_[date]
Access: L2 self-log · L3+ view all · L4+ edit
Feeds into: Turnover · Budget Hours · Payroll report
Status: ✅ GPS flag not block · Photo via label+input
💰 Cash Pickup cp_
❤️ he_cashpickup_[station]_[date]
🧠 cpValidate() (V101)
🦵 cpFillTL() cpAdvance()
🐍 cpRender() (V101)
⚡ waCpuAlert()
Storage: he_cashpickup_[station]_[date]
Access: L2 initiate · L3 confirm · L4 deposit
Feeds into: CPU vs Sales Variance · DSR · Turnover
Status: ⚠️ Tail + Brain hooks need explicit naming — V101
🏍️ Moto Promo Coordinator mpco_
❤️ mpcoLoadIssued() mpcoSaveIssued() mpcoScopedKey()
🧠 mpcoCalc()
🦵 mpcoIssue() mpcoAcknowledge()
🐍 mpcoRenderList()
⚡ mpcoUpdateBadge()
Storage: he_motopromo_[station]_[date] ✅ scoped
Access: L2 TL acknowledges · L3 Coord issues · L4+ views all
Feeds into: Shift Log · Turnover
Status: ✅ Scoped V100-1 · Photo evidence · Closed loop
🪝 Accounts Acquisition acq_
❤️ acqLoad() acqSaveAll() he_acq_pipeline
🧠 — (add MRR calc V101)
🦵 acqSave() acqMoveStage() acqDelete()
🐍 acqRender() acqCard()
⚡ acqUpdateBadge()
Storage: he_acq_pipeline (global — L6+ only, acceptable)
Access: L6 Ops Officer · L7 Owner
Feeds into: Client Mgmt (when active) · Dev Log
Status: ✅ Built V100-1 · 6-stage journey · Full profile cards
👥 Accounts cm_
❤️ cmGetClients() cmSaveClients()
🧠 cmCheckApprovals()
🦵 cmRemoveClient() cmActivateClient()
🐍 cmRenderActive() cmRenderOnboarding()
⚡ cmUpdateOwnerBadge()
Storage: he_clients
Access: L5 Stn Owner setup · L6 Ops · L7 Owner
Feeds into: USER_DB · Station Settings · Acquisition (source)
Status: ⚠️ cmRemoveClient mixes Heart+Brain — V101 fix
💲 Price Monitor pm_
❤️ pmGetThresh() he_pricemonitor_
🧠 pmCalcPriceRow()
🦵 pmSubmitLog()
🐍 pmRenderToday() pmOpenModal()
⚡ pmShowAlert()
Storage: he_pricemonitor_[station]_[date]
Access: L2 TL logs · L4+ views all stations
Feeds into: Turnover · Variance · WA Alert
Status: ✅ Stable · 3-competitor support added V100
🚛 Delivery Variance dv_
❤️ he_deliveries_[station]_[date]
🧠 dvCalcVariance() dvCalcDrop() dvEthanolCheck() dvCheckPOMatch()
🦵 dvNewDelivery() dvInit()
🐍 dvDropPhotoCapture()
⚡ waStockAlert()
Storage: he_deliveries_[station]_[date]
Access: L3+ logs · L4+ audit
Feeds into: Variance Report · Stock Alert · Dipstick
Status: ⚠️ dvDropPhotoCapture mixes Heart+Brain — V101 fix
🔁 Shift Turnover to_
❤️ he_turnover_[station]_[date]
🧠 — (validate completeness)
🦵 toInit() toSubmit()
🐍 toRenderIssues()
⚡ toUpdateBadge()
Storage: he_turnover_[station]_[date]
Access: L2 TL submits · L3+ reads
Feeds into: Next shift briefing · DSR · L4 audit
Status: ⚠️ Final validator per Rule 7 — verify all modules surface here