grm/TROUBLESHOOTING.md

Troubleshooting

Symptom	Likely Cause	Solution
Pre-commit rejects commit message	Missing conventional format or GRM-N prefix present	Use feat: description format without GRM-N:
make molecule fails with runner_name is undefined	Verify playbook missing variable	Fixed in Phase 1.1; ensure you're on latest master
CI molecule job fails	Docker not available on runner host	Ensure Gitea runner host has Docker installed and running
Auto-merge doesn't trigger	Label not exactly ready-to-merge or CI checks not all green	Verify label spelling; check CI status
Vikunja task not updated after merge	VIKUNJA_TOKEN expired or task ID missing from commit	Regenerate token; verify merge commit has GRM-N: prefix
Post-merge can't find Vikunja task	Task not in project 6 or identifier mismatch	Verify task exists in Vikunja project 6 with correct identifier
make pytest-cov fails	Coverage below 100%	Add tests for new code paths
devx.tools.configure_repo fails	REPO_TOKEN missing or invalid	Set token with repo admin scope and re-run
configure_repo sets wrong status checks	Stale BRANCH_PROTECTION_CONFIG	Updated to include (pull_request) suffix; re-run configure_repo
Token visible in ps aux during install	Old version passed tokens via command line	Fixed: tokens now passed via temp file with 0600 permissions
remove-runner.yml leaves lingering enabled	Old version didn't disable lingering	Fixed: now runs loginctl disable-linger and removes subuid/subgid
apt cache update always reports changed	cache_valid_time: 0 forced update every run	Fixed: changed to cache_valid_time: 3600
Prune/service templates created even when docker_rootless_setup: false	Template tasks not guarded	Fixed: template creation now guarded by docker_rootless_setup