# Runbook: gutasktool development and push

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

## Location

Host:

```text
../gutasktool
```

Gerhard container:

```text
/opt/gutasktool
```

## Start clean

```bash
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:

```bash
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:

```bash
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:

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

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

```bash
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:

```bash
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

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

After push:

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

The branch should show no ahead/behind divergence.