m3taversal 4e20986c25 ship: add agent SOP, auto-deploy infrastructure, cleanup stale files

- AGENT-SOP.md: enforceable checklist for commit/review/deploy cycle
- auto-deploy.sh + systemd units: 2-min timer pulls from Forgejo, syncs
  to working dirs, restarts services only when Python changes, smoke tests
- prune-branches.sh: dry-run-by-default branch cleanup tool
- Delete root diagnostics/ (stale artifacts, all code moved to ops/)
- Delete 7 orphaned HTML prototypes (untracked, local-only)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-14 12:46:25 +01:00

2.7 KiB

Raw Blame History

Agent SOP: Ship, Review, Deploy

Load at session start. No exceptions.

Code Changes

Branch from main: git checkout -b {agent-name}/{description}
Make changes. One branch per task. One concern per PR.
Commit with agent-name prefix, what changed and why.
Push to Forgejo. Open PR with deploy manifest (see deploy-manifest.md).
Ganymede reviews. Address feedback on same branch.
Merge after approval. Delete branch immediately.
Auto-deploy handles the rest. Do not manually deploy.

Do Not

SCP files directly to VPS
Deploy before committing to the repo
Edit files on VPS directly
Send the same review request twice for unchanged code
Claim code exists or was approved without reading git/files to verify
Go from memory when you can verify from files
Reuse branch names (Forgejo returns 409 Conflict on closed PR branches)

Canonical File Locations

Code	Location
Pipeline lib	`ops/pipeline-v2/lib/`
Pipeline scripts	`ops/pipeline-v2/`
Diagnostics	`ops/diagnostics/`
Agent state	`ops/agent-state/`
Deploy/ops scripts	`ops/`
Claims	`core/`, `domains/`, `foundations/`
Agent identity	`agents/{name}/`

One location per file. If your path doesn't match this table, stop.

Verification Before Acting

Before editing: read the file. Never describe code from memory.
Before reviewing: check git log for prior approvals on the same files.
Before deploying: git status must show clean tree.
Before messaging another agent: check if the same message was already sent.

Branch Hygiene

Delete branch immediately after merge.
Nightly research branches: deleted after 7 days if unmerged.
Never leave a branch open with no active work.

Deploy

After merge to main, auto-deploy runs within 2 minutes on VPS:

Pulls latest main into deploy checkout
Syntax-checks all Python files
Syncs to working directories (pipeline, diagnostics, agent-state)
Restarts services only if Python files changed
Runs smoke tests (systemd status + health endpoints)

Manual deploy (only if auto-deploy is broken):

cd ops && ./deploy.sh --dry-run && ./deploy.sh --restart

Check auto-deploy status: journalctl -u teleo-auto-deploy -n 20

Shell and Python Safety

Run bash -n script.sh after modifying any shell script.
Never interpolate shell variables into Python strings via '$var'. Pass values via os.environ or sys.argv.
Never write credentials to .git/config. Use per-command git -c http.extraHeader.

Schema Changes

Any PR that changes a file format, DB table, or API response shape must follow ops/schema-change-protocol.md. Tag all consumers. Include migration.

2.7 KiB Raw Blame History