policy-enforcer¶

systemctl --user status jupyter-default.service
# ● jupyter-default.service - active (running)

journalctl --user -u jupyter-default.service -n 20
# No error messages

ujust jupyter status
# ✅ All checks passed

# Check if ~/.config files are staged for commit
if git diff --cached --name-only | grep -q '\.config/'; then
    echo "❌ POLICY VIOLATION: ~/.config files in commit"
    exit 1
fi

Task(subagent_type="config-integrity-enforcer",
     description="Investigate config file violation",
     prompt="Detected ~/.config file edit. Investigate and provide fix guidance.")

pre-commit run --all-files
# All hooks passed

# BAD - no parameter support
read -p "Enter value: " VALUE

# BAD - always requires TTY
CHOICE=$(ugum choose "option1" "option2")

# BAD - SKIP_CONFIRM is FORBIDDEN (see Check 8)
if [[ "$SKIP_CONFIRM" != "yes" ]]; then
    read -p "Continue? (y/N): "
fi

# GOOD - Rule of Intent pattern
ACTION="{{ ACTION }}"
if [[ -z "$ACTION" ]]; then
    # Interactive: show menu + confirmations
    ACTION=$(ugum choose "install" "start" "stop")
fi
# Non-interactive: execute directly (ACTION = intent)
case "${ACTION,,}" in
    install) do_install ;;
esac

# Check for oversized files (>30K)
OVERSIZED=$(find system_files/usr/share/bazzite-ai/just -name "*.just" -size +30k 2>/dev/null)
if [ -n "$OVERSIZED" ]; then
    echo "❌ OVERSIZED FILES DETECTED"
    echo "$OVERSIZED" | while read -r file; do
        SIZE=$(du -h "$file" | cut -f1)
        echo "  $file: $SIZE"
    done
    exit 1
fi

# Warn on approaching limit (>20K)
LARGE=$(find system_files/usr/share/bazzite-ai/just -name "*.just" -size +20k -size -30k 2>/dev/null)
if [ -n "$LARGE" ]; then
    echo "⚠️  WARNING: Files approaching size limit (>20K)"
    echo "$LARGE" | while read -r file; do
        SIZE=$(du -h "$file" | cut -f1)
        echo "  $file: $SIZE - Consider splitting proactively"
    done
fi

NN-bazzite-ai-<category>-<subcategory>.just
NN-bazzite-ai-<category>-<subcategory>-helpers.just

# ❌ External sudo elevation - FORBIDDEN
sudo ujust <command>
sudo ujust testing start
sudo just <command>
sudo just -f <file> <command>

# Scan documentation for forbidden patterns
DOCS_VIOLATIONS=$(grep -r "sudo ujust\|sudo just" docs/ README.md CLAUDE.md CONTRIBUTING.md 2>/dev/null | grep -v "❌ WRONG" | grep -v "FORBIDDEN" | grep -v "Policy #8" | wc -l)

# Scan justfiles for external sudo suggestions
JUST_VIOLATIONS=$(grep -r "sudo ujust\|sudo just" system_files/usr/share/bazzite-ai/just/ 2>/dev/null | grep -v "# sudo" | grep -v "#!/usr/bin/bash" -A20 | wc -l)

if [ "$DOCS_VIOLATIONS" -gt 0 ] || [ "$JUST_VIOLATIONS" -gt 0 ]; then
    echo "❌ SUDO USAGE POLICY VIOLATION"
    echo "Found: $DOCS_VIOLATIONS documentation violations, $JUST_VIOLATIONS justfile violations"
    exit 1
fi

# ✅ CORRECT: Recipe handles sudo internally
command-name:
    #!/usr/bin/bash
    set -euo pipefail

    # Validate sudo access upfront
    if ! sudo -v; then
        echo "Error: This command requires sudo privileges"
        exit 1
    fi

    # Use sudo for specific operations
    sudo systemctl enable service

# ❌ Direct justfile execution for testing - FORBIDDEN
just -f system_files/usr/share/bazzite-ai/just/jupyter-install.just install-jupyter
sudo just -f .../testing.just testing start
just -f <any-file> <any-command>

# Scan testing documentation for just -f
TEST_VIOLATIONS=$(grep -r "just -f" docs/developer-guide/testing/ docs/developer-guide/validation-checklist.md docs/developer-guide/troubleshooting.md 2>/dev/null | grep -v "❌ WRONG" | grep -v "FORBIDDEN" | grep -v "Policy #9" | wc -l)

# Scan user guides for just -f bootstrap
USER_VIOLATIONS=$(grep -r "just -f" docs/user-guide/ docs/getting-started/ 2>/dev/null | grep -v "just build" | wc -l)

if [ "$TEST_VIOLATIONS" -gt 0 ] || [ "$USER_VIOLATIONS" -gt 0 ]; then
    echo "❌ OVERLAY-ONLY TESTING POLICY VIOLATION"
    echo "Found: $TEST_VIOLATIONS testing doc violations, $USER_VIOLATIONS user guide violations"
    exit 1
fi

# ✅ CORRECT: Overlay testing method
# 1. Bootstrap overlay session
ujust testing start

# 2. Test with real ujust
ujust install-jupyter

# 3. Verify on LOCAL system
systemctl --user status jupyter-default.service
journalctl --user -u jupyter-default.service -n 50

# CRITICAL: Scan for FORBIDDEN confirmation bypass parameters
FORBIDDEN_FOUND=$(grep -rn -E 'SKIP_CONFIRM=""|CONFIRM=""|FORCE=""|FORCE_REINSTALL=""' \
  system_files/usr/share/bazzite-ai/just/*.just \
  system_files/usr/share/bazzite-ai/just/lib/*.just 2>/dev/null | grep -v "# FORBIDDEN" | wc -l)

if [ "$FORBIDDEN_FOUND" -gt 0 ]; then
    echo "❌ FORBIDDEN CONFIRMATION BYPASS PARAMETERS DETECTED"
    grep -rn -E 'SKIP_CONFIRM=""|CONFIRM=""|FORCE=""|FORCE_REINSTALL=""' \
      system_files/usr/share/bazzite-ai/just/*.just \
      system_files/usr/share/bazzite-ai/just/lib/*.just 2>/dev/null | grep -v "# FORBIDDEN"
    exit 1
fi

# OLD (FORBIDDEN) → NEW (Rule of Intent)
SKIP_CONFIRM=""    → ACTION value (e.g., "end-reboot")
CONFIRM=""         → ACTION value
FORCE=""           → ACTION value (e.g., "force-stop")
FORCE_REINSTALL="" → ACTION value (e.g., "reinstall")

# Check if pixi.lock is being edited directly (not regenerated)
# Look for Edit/Write tool usage on pixi.lock files

STAGED=$(git diff --cached --name-only)
# Check: If pixi.toml staged, pixi.lock should also be staged
# Check: If pixi.lock staged alone, verify it was regenerated

Task(subagent_type="pixi-lock-enforcer",
     description="Investigate pixi.lock violation",
     prompt="Detected pixi.lock edit or unpaired commit. Investigate and provide fix guidance.")

✅ POLICY COMPLIANCE VERIFIED

All critical policies followed:
- ✅ Check 1: LOCAL system verification confirmed (Policy #1)
- ✅ Check 2: Config file integrity maintained (Policy #3)
- ✅ Check 3: Pre-commit validation passed (Policy #4)
- ✅ Check 4: Non-interactive support implemented (Policy #5)
- ✅ Check 5: File size limits compliant (Policy #6)
- ✅ Check 6: Sudo usage policy compliant (Policy #8)
- ✅ Check 7: Overlay-only testing compliant (Policy #9)
- ✅ Check 8: No forbidden confirmation bypass parameters
- ✅ Check 9: Pixi lock integrity maintained (Policy #7)

Safe to proceed with commit.

❌ POLICY VIOLATION DETECTED

Policy: [Which policy violated]

Issue: [What's wrong - specific details]

Evidence: [What was found or missing]

Required Action: [What must be done to fix]

Reference: docs/developer-guide/policies.md#[anchor]

BLOCKING commit until policy compliance verified.

❌ POLICY VIOLATION DETECTED

Policy: LOCAL System Verification Requirements

Issue: No evidence of LOCAL system testing found.

Evidence:
- No systemctl status checks shown
- No journalctl log examination
- No service functionality verification
- Only pre-commit hooks were run (syntax only)

Required Action:
1. Test using overlay testing:
   ujust testing start  # Bootstrap (one-time)
   ujust install-jupyter                 # Test command

2. Verify on LOCAL system:
   systemctl --user status jupyter-default.service
   journalctl --user -u jupyter-default.service -n 50
   ujust jupyter status

3. Confirm all 8 testing standards met

Reference: docs/developer-guide/policies.md#local-verification

BLOCKING commit until LOCAL verification performed.

❌ POLICY VIOLATION DETECTED

Policy: Configuration File Integrity Mandate

Issue: Direct config file modification detected (hot-patching).

Evidence:
Changes found in ~/.config/containers/systemd/config.toml
No corresponding changes in source justfile

Required Action:
1. Revert changes to ~/.config/containers/systemd/config.toml
2. Fix SOURCE code in:
   just/bazzite-ai/dev-jupyter.just
3. Test by running the command:
   ujust jupyter-remove-instance
   ujust jupyter-add-instance
4. Verify config regenerated correctly

Reference: docs/developer-guide/policies.md#config-integrity

BLOCKING commit. Fix source code, not output configs.

❌ POLICY VIOLATION DETECTED

Policy: Pre-Commit Validation Requirements

Issue: Pre-commit hooks not run or failed.

Evidence:
- No pre-commit output shown
- Files modified without validation
- Attempting to commit without passing checks

Required Action:
1. Run pre-commit validation:
   pre-commit run --all-files

2. Fix ALL failing hooks:
   - ShellCheck errors
   - yamllint errors
   - markdownlint errors
   - just --fmt errors

3. Re-run validation until 100% pass

4. NEVER use --no-verify flag

Reference: docs/developer-guide/policies.md#pre-commit-validation

BLOCKING commit until all hooks pass.

❌ POLICY VIOLATION DETECTED

Policy: Non-Interactive Command Requirements

Issue: New command requires TTY (no parameter support).

Evidence:
Recipe: toggle-new-service
Uses: read -p without parameter alternative
Will fail in: CI/CD, automation, non-interactive environments

Required Action:
1. Add parameter support:
   toggle-new-service ACTION="":
       #!/usr/bin/bash
       ACTION="{{ ACTION }}"
       if [[ -z "$ACTION" ]]; then
           ACTION=$(ugum choose "enable" "disable")
       fi

2. Test non-interactive mode:
   ujust toggle-new-service enable  # Non-interactive with parameter

3. Document parameters in help text

Reference: docs/developer-guide/policies.md#non-interactive-requirements

BLOCKING commit until parameter support added.

❌ POLICY VIOLATION DETECTED

Policy: No Confirmation Bypass Parameters (Check 8)

Issue: Forbidden confirmation bypass parameter detected in recipe.

Evidence:
system_files/usr/share/bazzite-ai/just/testing.just:
  Line 42: testing ACTION="" SKIP_CONFIRM="":
  Line 47: if [[ "$SKIP_CONFIRM" != "yes" ]]; then

Parameters detected: SKIP_CONFIRM=""

Problem:
- SKIP_CONFIRM, CONFIRM, FORCE, FORCE_REINSTALL are DEPRECATED
- These parameters violate the "Rule of Intent" principle
- Use ACTION values instead for non-interactive behavior

Required Action:
1. Remove SKIP_CONFIRM parameter from recipe header
2. Move confirmation logic inside interactive mode check
3. Add ACTION value for non-interactive behavior:

   # BEFORE (FORBIDDEN)
   testing ACTION="" SKIP_CONFIRM="":
       if [[ "$SKIP_CONFIRM" != "yes" ]]; then
           read -p "Reboot? (y/N): "
       fi

   # AFTER (Rule of Intent)
   testing ACTION="":
       case "${ACTION,,}" in
           end)        _testing-end ;;
           end-reboot) _testing-end && systemctl reboot ;;
           reboot)     _testing-end && systemctl reboot ;;
       esac

Reference: CLAUDE.md#policy-5-non-interactive-command-requirements

BLOCKING commit. Migrate to Rule of Intent pattern.

❌ POLICY VIOLATION DETECTED

Policy: File Size Limit Mandate

Issue: .just file exceeds 30K hard limit.

Evidence:
- system_files/usr/share/bazzite-ai/just/jupyter-install.just: 23K (within limits)
- Hard limit: 30K (30720 bytes)
- Warning threshold: 25K
- Monitor and consider splitting if it grows further

Required Action if file exceeds 30K:
1. Identify logical split points:
   - Group related recipes (Jupyter installation, Jupyter status, Jupyter ports)
   - Separate helper functions
   - Split by service/feature

2. Create focused files:
   containers-virt-jupyter.just (Jupyter service)
   containers-virt-sunshine.just (Sunshine service)
   containers-virt-helpers.just (Shared helpers)

3. Update cross-file references:
   !include {{ justfile_directory() }}/containers-virt-jupyter.just

4. Test all recipes after split:
   just -f system_files/.../containers-virt-jupyter.just jupyter install

5. Run pre-commit validation on all new files

6. Delete original oversized file

Reference: docs/developer-guide/policies.md#file-size-limits

BLOCKING commit. File must be <30K.

⚠️  POLICY WARNING

Policy: File Size Limit Mandate (Warning Threshold)

Issue: .just file approaching size limit (>20K).

Evidence:
- system_files/usr/share/bazzite-ai/just/dev-core.just: 18K
- Warning threshold: 20K
- Hard limit: 30K
- Currently within limits but monitor for growth

Recommendation:
Consider splitting proactively to avoid hitting hard limit:
1. File still under 30K - commit is allowed
2. Growth trend suggests future violation
3. Early split is easier than emergency refactor
4. Better maintainability with smaller files

Split strategy:
- Group by service (docker, podman, dev-tools)
- Maintain logical cohesion
- Test after split

Reference: docs/developer-guide/policies.md#file-size-limits

This is a WARNING. Commit allowed but split recommended.

❌ POLICY VIOLATION DETECTED

Policy: Configuration File Integrity Mandate

Issue: ~/.config files detected in git commit (about to be committed).

Evidence:
git diff --cached --name-only shows:
- .config/jupyter/cfg/config.toml
- .config/systemd/user/jupyter-default.service

Problem:
- ~/.config files are OUTPUT configs (generated by ujust commands)
- Should NEVER be committed to repository
- Source code in system_files/ should be modified instead
- These files will be regenerated on every system

Required Action:
1. Unstage ~/.config files:
   git reset HEAD .config/

2. Identify what you were trying to fix in the config

3. Fix the SOURCE code that generates the config:
   vim system_files/usr/share/bazzite-ai/just/jupyter-install.just

4. Test by regenerating config:
   ujust jupyter-remove-instance
   ujust jupyter-add-instance

5. Verify config is correct:
   cat ~/.config/containers/systemd/config.toml

6. Commit SOURCE changes only:
   git add system_files/
   git commit -m "Fix: correct GPU encoder detection"

Reference: docs/developer-guide/policies.md#config-integrity

BLOCKING commit. Remove ~/.config files from staging area.

# Look for service status checks in conversation
grep -i "systemctl.*status" conversation

# Look for log checks
grep -i "journalctl" conversation

# Look for functionality verification
grep -i "check-" conversation

# Check if ~/.config files modified recently
find ~/.config -mtime -1 -type f

# Check if ~/.config files are staged for commit (CRITICAL)
git diff --cached --name-only | grep '\.config/'

# Check if ~/.config files are in working directory changes
git status --short | grep '\.config/'

# Check if source files modified (should be modified instead)
git diff --name-only system_files/
git diff --name-only build_files/

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

# Check for --no-verify usage
git log -1 --pretty=format:"%s %b" | grep -i "no-verify"

# Look for parameter definitions
grep -E '^[a-z-]+( [A-Z_]+="")*:' system_files/usr/share/bazzite-ai/just/*.just

# Check for read -p or ugum without parameter
grep -E 'read -p|ugum choose' system_files/usr/share/bazzite-ai/just/*.just

# Check for oversized files (>30K)
find system_files/usr/share/bazzite-ai/just -name "*.just" -size +30k

# Check for large files approaching limit (>20K)
find system_files/usr/share/bazzite-ai/just -name "*.just" -size +20k -size -30k

# Get exact sizes of all .just files
find system_files/usr/share/bazzite-ai/just -name "*.just" -exec ls -lh {} \; | \
  awk '{print $5 "\t" $9}'

# CRITICAL: Scan for FORBIDDEN parameters in recipe headers
# These MUST return empty if compliant

# Check for SKIP_CONFIRM (FORBIDDEN)
grep -rn 'SKIP_CONFIRM=""' system_files/usr/share/bazzite-ai/just/

# Check for CONFIRM (FORBIDDEN)
grep -rn 'CONFIRM=""' system_files/usr/share/bazzite-ai/just/ | grep -v SKIP_CONFIRM

# Check for FORCE (FORBIDDEN - use ACTION="force-stop" instead)
grep -rn 'FORCE=""' system_files/usr/share/bazzite-ai/just/ | grep -v FORCE_

# Check for FORCE_REINSTALL (FORBIDDEN)
grep -rn 'FORCE_REINSTALL=""' system_files/usr/share/bazzite-ai/just/

# All-in-one check (MUST return empty if compliant)
grep -rn -E 'SKIP_CONFIRM=""|CONFIRM=""|FORCE=""|FORCE_REINSTALL=""' \
  system_files/usr/share/bazzite-ai/just/*.just \
  system_files/usr/share/bazzite-ai/just/lib/*.just 2>/dev/null