# Repo and Agent Workspace Isolation

## Purpose

Prevent multiple agents from colliding in dirty working trees, leaving partial work that blocks other agents, or mixing unrelated projects in a single git repository.

This policy complements:

- `docs/context-hygiene-and-handover.md` — dirty-work triage, terminated-agent recovery, handover rules
- `docs/templates/terminated-agent-recovery-template.md`

## Core Rule

Do not add implementation work to a dirty working tree by default. If `git status --short` shows unrelated dirty files, choose one of:

1. **Stop and triage** — inspect the dirty files, classify them, decide keep/revert/move/commit.
2. **Create an isolated branch or worktree** — branch off from the current HEAD and work there.
3. **Use a separate clone/repo** — for service-specific work that belongs in its own repository.
4. **Proceed in-place** — only with explicit user approval or for narrow recovery/documentation work that does not add to the noise.

## When Work Stays in the Nimrod Repo

The Nimrod repo (`nimrod`) is the **coordination, operations, and process** repository.

Keep in Nimrod:

- Tickets and specs (`tickets/`)
- Runbooks and operations documentation (`runbooks/`, `docs/`)
- Infrastructure registry and inventory (`infra/`, `systems/`)
- Agent configuration (`.pi/agents/`, `.pi/extensions/`)
- Service deployment defaults and templates (`docs/templates/`)
- Change logs, handovers, and session summaries
- Ansible playbooks and inventory (`ansible/`)
- SSH configuration references (`.pi/ssh/`)
- Scratch notes, capture, and non-service project notes (`inbox/`, `projects/`)

Do not keep in Nimrod:

- Service source code, application config files, or Dockerfiles for service-specific projects
- Large binary artifacts or backups
- Secrets, credentials, tokens, or private keys (not even in git-ignored test directories)
- Service data or databases

## When Work Moves to a Service-Specific Repo

Create a separate repo for a service when:

- The service has its own source code, application config, or Docker Compose that changes independently from the operations workflow.
- The service needs its own issue/PR review lifecycle separate from Nimrod's operational tickets.
- Multiple agents may need to work on the service and Nimrod simultaneously without blocking each other.

**Adding a service repo does not remove operational responsibility from Nimrod.** The Nimrod repo keeps runbooks, backup procedures, DNS records, and change logs for the service. The service repo keeps the service's own source/config/code.

### Service Repo Naming Convention

```
/home/piagent/projects/<service-name>/
```

Examples:
- `/home/piagent/projects/nimrod/` — the coordination repo (already exists)
- `/home/piagent/projects/vaultwarden/` — Vaultwarden-specific config and deployment scripts
- `/home/piagent/projects/searxng/` — SearXNG compose files, custom settings
- `/home/piagent/projects/homepage/` — Homepage dashboard config if it outgrows Ansible-managed files

### Cross-Repo Referencing Convention

When a ticket or spec in Nimrod needs to reference a service repo, use:

```text
Service repo: `/home/piagent/projects/<name>/`
Nimrod ticket/spec root: `tickets/<ticket-id>/`
Nimrod runbook: `runbooks/<service>.md`
Nimrod infra registries: `infra/`
```

Cross-repo references in markdown should use the absolute or project-relative path. Do not clone the service repo into the Nimrod repository.

## Branch and Worktree Conventions

### Branch Naming

When working in a shared repo where multiple agents may need isolated branches:

- Use `agent/<agent-name>/<short-description>` format.
- Example: `agent/preflight/unbound-backup-backfill`

### Git Worktrees

For agents that need to work on different branches simultaneously, use `git worktree`:

```sh
# Create a worktree for an isolated task
git worktree add /tmp/worktree-isolated-<task> <base-branch>

# Work in the worktree
cd /tmp/worktree-isolated-<task>
# ...make changes, commit, push...

# Remove the worktree when done
cd /home/piagent/projects/nimrod
git worktree remove /tmp/worktree-isolated-<task>
```

Worktrees should be created under `/tmp/` for disposable agent isolation, or under `/home/piagent/projects/worktrees/` for longer-lived branches.

### When to Use Each

| Situation | Recommended approach |
|---|---|
| Quick doc fix on clean tree | Proceed in-place |
| Isolated ticket on clean tree, one agent | Proceed in-place on a feature branch |
| Same repo, multiple concurrent agents | Worktrees on independent branches |
| Service code/config separate from ops | Separate service repo |
| Dirty tree, small unrelated change needed | Worktree or separate clone |
| Mid-task agent termination | Follow terminated-agent recovery checklist first; do not add new work in-place |

## Terminated-Agent Recovery

See `docs/context-hygiene-and-handover.md` for the dirty-work triage flow and `docs/templates/terminated-agent-recovery-template.md` for the structured recovery form.

Always follow this path on recovery:

1. `git status --short && git diff --stat` — survey the state.
2. Classify each change: related to the intended task / unrelated / unknown.
3. For unrelated / unknown: triage before adding new work.
4. For related: continue from partial work **only** if the scope is clear and the task is the current active ticket.
5. If continuing, update or write a fresh handover rather than inheriting the previous agent's context.

## Service Repo Lifecycle

When a service gets its own repo:

1. Create the repo directory under `/home/piagent/projects/`.
2. Initialize it as a git repo with a `README.md` explaining the repo's purpose.
3. Add a `LINKED-TO-NIMROD.md` (or equivalent) pointing to the Nimrod ticket and runbook.
4. Update the Nimrod registry `infra/proxmox-registry.yaml` to note the separate repo.
5. The Nimrod runbook should reference the external repo where relevant.
6. Operational changes (backups, DNS, monitoring) remain documented in Nimrod.

## Enforcement

This policy is enforced at the agent's own preflight gate:

- At fresh context start (AGENTS.md rule 6): run `git status --short`; if dirty and unrelated, triage or isolate.
- At any point before new implementation work: check tree state.
- For infra work (DevOps coordination rules): also check `state/locks/` and live system state.

Violations (adding implementation work to a dirty tree covering unrelated tasks) should be corrected with the user before continuing.