Runbook: gutasktool development and push

Use this when an agent must inspect, fix, or push gutasktool.

Location

Host:

../gutasktool

Gerhard container:

/opt/gutasktool

Start clean

cd /opt/gutasktool
git fetch origin
git status --short --branch --untracked-files=all
git log --oneline --decorate --max-count=10 --all

If local branch is behind origin, pull or rebase before editing.

If local branch is ahead and behind, inspect the local commits before rebasing:

git log --oneline --decorate --graph --max-count=20 --all
git diff --stat origin/main...HEAD
git diff --name-status origin/main...HEAD

Create a backup branch before risky reconciliation:

git branch backup/local-before-rebase-$(date +%Y%m%d-%H%M%S)
git rebase origin/main

Resolve conflicts deliberately. Do not discard local work unless the human asks.

Edit

Make the smallest change that fixes the problem.

Avoid secrets. Do not read .env unless explicitly needed and approved.

Verify

At minimum:

python3 -m py_compile gutasktool/cli.py
git diff --check

If requests is missing on the host, create a temporary venv:

tmpvenv=$(mktemp -d /tmp/gutasktool-venv.XXXXXX)
python3 -m venv "$tmpvenv"
"$tmpvenv/bin/python" -m pip install -q 'requests>=2.28'
PYTHONPATH=. "$tmpvenv/bin/python" -m py_compile gutasktool/cli.py
PYTHONPATH=. "$tmpvenv/bin/python" -c 'import sys; from gutasktool.cli import main; sys.argv=["gutask","orient","--help"]; main()'

For orientation support, verify help and env behavior:

PYTHONPATH=. "$tmpvenv/bin/python" -c 'import sys; from gutasktool.cli import main; sys.argv=["gutask","orient","--help"]; main()'
AGENT_ID=123 API_URL=http://example.invalid CONTENT_API_KEY=dummy PYTHONPATH=. "$tmpvenv/bin/python" -c 'import sys; from gutasktool.cli import main; sys.argv=["gutask","orient"]; main()'

The second command should attempt a connection using env-provided AGENT_ID, not fail with missing agent identity.

Commit and push

git add <changed-files>
git commit -m "feat: clear description"
git push origin main

After push:

git fetch origin
git status --short --branch
git log --oneline --decorate --max-count=3

The branch should show no ahead/behind divergence.

2.3 KiB Raw Blame History