Development Policies¶

This page summarizes the 10 core development policies that ensure code quality and system stability.

Policy Summary Table¶

Policy Details¶

1. LOCAL Verification¶

Rule: Test functionality on the LOCAL system before declaring anything "working."

Why: Pre-commit hooks validate syntax only, not functionality. A command may pass all linting checks but fail at runtime.

Required Verification:

# 1. Check service status
systemctl --user status <service>

# 2. Review logs for errors
journalctl --user -u <service> -n 50

# 3. Test actual functionality
ujust <command>

Forbidden:

• Claiming "this works" without LOCAL verification
• Skipping service status/log checks

2. Root Cause Analysis¶

Rule: Investigate ALL unexpected behavior. Never rationalize errors as "expected."

Triggers:

• Any error message in output
• Service fails to start
• Invalid HTTP codes
• Connection failures or timeouts
• Logs showing ERROR/WARN/FAIL

Required Process:

1. STOP - Don't proceed
2. DOCUMENT - Capture the error
3. ASK WHY - Question assumptions
4. INVESTIGATE - Gather context
5. HYPOTHESIZE - Form theory
6. TEST - Verify hypothesis
7. FIX - Address root cause
8. VERIFY - Confirm resolution

Forbidden:

• "This error is probably expected"
• Skipping investigation to save time
• Debugging without the subagent

3. Config Integrity¶

Rule: Configuration files in ~/.config/ are GENERATED OUTPUTS. Edit the source code that generates them.

Workflow:

Source Code                    → ujust command → Generated Output
system_files/.../*.just        → ujust <cmd>   → ~/.config/...

Forbidden:

# NEVER do this:
vim ~/.config/systemd/user/*.service
sed -i 's/old/new/' ~/.config/containers/*.conf

Correct Approach:

# Edit source instead:
vim system_files/usr/share/bazzite-ai/just/*.just

# Then regenerate:
ujust <command> config

4. Pre-Commit Validation¶

Rule: 100% pass rate on pre-commit hooks before any commit.

Hooks (8 total):

Workflow:

# Run before commit
pre-commit run --all-files

# If failures, fix and re-run
# NEVER use --no-verify

5. Non-Interactive Commands¶

Rule: Every ujust command MUST support non-interactive execution via explicit parameters.

Pattern:

# Interactive (menu-based)
ujust jupyter

# Non-interactive (automation-friendly)
ujust jupyter start
ujust jupyter start --port=8889

Required Recipe Pattern:

recipe ACTION="":
    #!/usr/bin/bash
    if [[ -z "$ACTION" ]] && [[ -t 0 ]]; then
        ACTION=$(ugum choose "start" "stop" "config")
    fi
    # Handle action

Forbidden Parameters:

• SKIP_CONFIRM
• CONFIRM
• FORCE
• FORCE_REINSTALL

6. File Size Limits¶

Rule: .just files must be under 30KB. Split proactively when reaching 20-25KB.

Limits:

Split Strategy:

• Logical boundaries (services, features)
• Helper recipes to separate files
• Use import to include split files

Check:

find system_files -name "*.just" -exec ls -lh {} \;

7. Pixi Lock Integrity¶

Rule: The pixi.lock file must be regenerated using pixi install, never edited manually.

Correct Workflow:

# 1. Edit pixi.toml with package changes
vim pixi.toml

# 2. Regenerate lock file
pixi install

# 3. Commit both files together
git add pixi.toml pixi.lock

Forbidden:

# NEVER do this:
vim pixi.lock
sed -i 's/old/new/' pixi.lock

8. Sudo Usage¶

Rule: ujust commands handle sudo internally when needed. Never invoke with sudo.

Correct:

ujust docker enable      # Handles sudo internally
ujust nvidia-kargs       # Prompts for sudo if needed

Forbidden:

sudo ujust docker enable  # WRONG - permission errors
sudo just build           # WRONG - breaks user context

Why: Running with sudo breaks:

• User-specific paths ($HOME)
• Systemd user services
• Container configurations

9. Overlay Testing¶

Rule: Use the overlay testing method, not just -f with direct justfile paths.

Why just -f Fails:

• Doesn't test real ujust behavior
• Wrong path resolution
• Missing system context
• False positives

Correct Method:

# 1. Enable overlay (one-time per session)
just test overlay enable

# 2. Test with real ujust
ujust <command>

# 3. After changes, refresh overlay
just test overlay refresh

# 4. Disable (reboot ends session)
systemctl reboot

10. Branch Workflow¶

Rule: All development happens on the testing branch. Never commit directly to main.

Workflow:

# Development
git checkout testing
# ... make changes ...
git commit -m "Fix: description"
git push origin testing

# Merge to main (via PR or after CI passes)
git checkout main
git merge testing
git push origin main

Branches:

Complete Reference¶

For complete policy details including AI enforcement procedures, see:

• AI Enforcement Framework - Subagent system and triggers
• CLAUDE.md - Full AI development guide
• AGENTS.md - Commands and architecture