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:

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

If brv query fails, use:

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:

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:

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:

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:

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:

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:

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.