opusmanSEEKv4/github_brv_sandbox_runbook.md

# Nexus GitHub, BRV, And Sandbox Runbook

Status: workflow draft for repeatable private-repo sync.
Scope: canonical `NEXUS`, Zo/cloud work, NEO autonomous work, ByteRover memory sync, and agent sandbox boundaries.

## Grounding Order

Before any sync or handoff:

1. Read `01_PROJECT_STATE.md`.
2. Check `AGENTS.md` for repository rules.
3. Check the live tree with `git status --short`.
4. Query BRV when available:

```powershell
brv query "Nexus current sync, branch, sandbox, and governance rules"
```

If `brv query` fails, use:

```powershell
brv search "Nexus sync branch sandbox governance" --limit 10 --format json
```

If BRV fails inside Codex, use normal Windows Terminal/PowerShell or read `.brv/context-tree/` directly. Do not curate or approve memory changes while BRV is unhealthy.

## Branch And PR Flow

Use this flow for canonical `NEXUS`, Zo/cloud, and NEO-derived changes.

1. Start clean enough to isolate the task:

```powershell
git status --short
git remote -v
git fetch --all --prune
git switch main
git pull --ff-only
git switch -c <type>/<short-task-name>
```

2. Confirm the remote is the intended private GitHub repository before pushing. Do not push local-only or public-share material to the wrong remote.

3. Work only in the agreed ownership area. For agent slices, avoid touching unrelated files and never revert edits made by another agent.

4. Verify before publishing:

```powershell
git status --short
git diff --check
```

For docs-only changes, `git diff --check` is the minimum gate. For code, run focused tests; for core DB/router/governor/bridge/vault/GMR changes, run the full suite unless blocked.

5. Stage explicit reviewed paths only:

```powershell
git add -- <path1> <path2>
git diff --cached --check
git commit -m "<type>(scope): <behavioral change>"
```

Do not use `git add .`.

6. Push and open PR:

```powershell
git push -u origin HEAD
gh pr create --base main --head <branch> --title "<title>" --body "<summary, verification, risk>"
```

PR body must include verification evidence, changed ownership area, and any known sandbox/private material excluded from the branch.

## Repository Roles

Canonical `NEXUS`:
- Path: `C:\Users\speci.000\Documents\NEXUS`.
- Source of truth for governance, orchestration, canonical docs, tests, and share gates.
- Only reconciled, tested, reviewable changes belong here.

Zo/cloud:
- Cloud OpenClaw/T4 work is coordination and execution support, not an override of canonical state.
- Cloud outputs must return as branches, PRs, logs, or sanitized reports.
- Do not push raw cloud credentials, provider state, heavy benchmark outputs, model files, or cost/private telemetry.

NEO autonomous folder:
- Treat `C:\Users\speci.000\Documents\NEO agent` and `C:\Users\speci.000\Documents\OPENcode\NEO` as adjacent/reference workspaces.
- Promote useful material only through: evidence -> task/proposal -> branch -> focused tests/docs -> PR.
- Never copy `.env`, local DBs, raw evidence, gitleaks reports, caches, `.opencode`, `.kilo`, `.kilocode`, archives, or model/runtime artifacts into canonical `NEXUS`.

## BRV Memory Sync

BRV memory lives under `.brv/context-tree/` and has its own version-control flow.

Use current commands:

```powershell
brv vc status
brv vc pull
brv review pending
brv curate "<short verified project fact>" -f <source-file>
brv review pending
brv vc status
brv vc push
```

Rules:
- Use `brv vc push` and `brv vc pull`; do not use deprecated `brv push` or `brv pull`.
- Review pending high-impact operations against `01_PROJECT_STATE.md`, current tests, and leak-scan evidence before approval.
- If a memory claim is stale, reject it and curate a corrected baseline instead.
- Keep `.brv.backup-*` local and ignored.
- If BRV and tracked docs disagree, tracked docs, git state, filesystem state, and test output win.

## Agent Sandbox Rules

Every agent must stay inside its assigned ownership boundary.

Required:
- Check `git status --short` before edits and before final response.
- Read files before making claims about them.
- Keep changes bounded to one coherent task slice.
- Leave unrelated modified or untracked files untouched.
- Report changed files and verification evidence.

Forbidden:
- Reverting another agent's edits without explicit approval.
- Staging sandbox files, mock secrets, raw research dumps, model weights, generated caches, unreviewed downloads, or local archives.
- Deleting local models or archives without inventory, backup, and rollback path.
- Exposing Ollama, private weights, DoppelGround raw sessions, or core TWAVE internals to external teams.
- Promoting public/private repo material before leak/share gates pass.

## Minimal Handoff Checklist

Use this at the end of each sync slice:

```text
Branch:
Changed files:
Verification:
BRV status:
Excluded private/sandbox material:
PR link:
Open risks:
```

No slice is complete without concrete evidence: diff, command output, test output, reviewed artifact, or PR link.

## 12-Hour Health Automation Loop

The `nexus-health-check` automation should run every 12 hours and stay quiet
when there is no actionable queue work.

Required behavior:
- Read `01_PROJECT_STATE.md`, `AGENTS.md`, `git status --short --branch`, and the automation memory first.
- Query BRV only when it is healthy in the current shell; if Codex-shell BRV fails, record the failure in automation memory and continue with tracked docs.
- Process only official task files from `tasks/pending/` or explicit health-check tasks.
- If the queue is empty, do not edit repository files, do not stage files, and do not append to `docs/operations/worklog.md`.
- If tasks exist, claim or process oldest-first, verify with narrow tests after each task, then move completed task files to the correct completed/done location.
- Report pre-existing untracked files without modifying them.
- End every run with: tasks processed count, verification summary, repo changed yes/no, BRV status, and open blockers.

This prevents zombie progress: a health run that finds no tasks must produce
only a short status summary and memory update, not synthetic repo activity.