the-nexus/README.md

# Nexus Organization Policy

## Branch Protection & Review Requirements

All repositories must enforce these rules on the `main` branch:
- ✅ Require Pull Request for merge
- ✅ Require 1 approval
- ✅ Dismiss stale approvals
- ✅ Require CI to pass (where ci exists)
- ✅ Block force pushes
- ✅ block branch deletion

### Default Reviewers
- @perplexity - All repositories (QA gate)
- @Timmy - hermes-agent (owner gate)

### Implementation Status
- [x] hermes-agent
- [x] the-nexus
- [x] timmy-home
- [x] timmy-config

### CI Status
- hermes-agent: ✅ ci enabled
- the-nexus: ⚠ ci pending (#915)
- timmy-home: ❌ No ci
- timmy-config: ❌ No ci
| Require PR for merge | ✅ Enabled | hermes-agent, the-nexus, timmy-home, timmy-config |
| Required approvals | ✅ 1+ required | All |
| Dismiss stale approvals | ✅ Enabled | All |
| Require CI to pass | ✅ Where CI exists | hermes-agent (CI active), the-nexus (CI pending) |
| Block force push | ✅ Enabled | All |
| Block branch deletion | ✅ Enabled | All |

## Default Reviewer Assignments

- **@perplexity**: Default reviewer for all repositories (QA gate)
- **@Timmy**: Required reviewer for `hermes-agent` (owner gate)
- **Repo-specific owners**: Required for specialized areas

## CI Status

- ✅ Active: hermes-agent
- ⚠️ Pending: the-nexus (#915)
- ❌ Disabled: timmy-home, timmy-config

## Acceptance Criteria

- [x] Branch protection enabled on all repos
- [x] @perplexity set as default reviewer
- [ ] CI restored for the-nexus (#915)
- [x] Policy documented here

## Implementation Notes

1. All direct pushes to `main` are now blocked
2. Merges require at least 1 approval
3. CI failures block merges where CI is active
4. Force-pushing and branch deletion are prohibited

See Gitea admin settings for each repository for configuration details.

It is meant to become two things at once:
- a local-first training ground for Timmy
- a wizardly visualization surface for the living system

## Current Truth

As of current `main`, this repo does **not** ship a browser 3D world.
In plain language: current `main` does not ship a browser 3D world.

A clean checkout of `Timmy_Foundation/the-nexus` on `main` currently contains:
- Python heartbeat / cognition files under `nexus/`
- `server.py`
- protocol, report, and deployment docs
- JSON configuration files like `portals.json` and `vision.json`

It does **not** currently contain an active root frontend such as:
- `index.html`
- `app.js`
- `style.css`
- `package.json`

Serving the repo root today shows a directory listing, not a rendered world.

## One Canonical 3D Repo

`Timmy_Foundation/the-nexus` is the only canonical 3D repo.
In plain language: Timmy_Foundation/the-nexus is the only canonical 3D repo.

The old local browser app at:
- `/Users/apayne/the-matrix`

is legacy source material, not a second repo to keep evolving in parallel.
Useful work from it must be audited and migrated here.

See:
- `LEGACY_MATRIX_AUDIT.md`

## Why this matters

We do not want to lose real quality work.
We also do not want to keep two drifting 3D repos alive by accident.

The rule is:
- rescue good work from legacy Matrix
- rebuild inside `the-nexus`
- keep telemetry and durable truth flowing through the Hermes harness
- keep OpenClaw as a sidecar, not the authority

## Verified historical browser-world snapshot

The commit the user pointed at:
- `0518a1c3ae3c1d0afeb24dea9772102f5a3d9a66`

still contains the old root browser files (`index.html`, `app.js`, `style.css`, `package.json`, tests/), so it is a useful in-repo reference point for what existed before the later deletions.

## Active migration backlog

- `#684` sync docs to repo truth
- `#685` preserve legacy Matrix quality work before rewrite
- `#686` rebuild browser smoke / visual validation for the real Nexus repo
- `#687` restore a wizardly local-first visual shell from audited Matrix components
- `#672` rebuild the portal stack as Timmy → Reflex → Pilot
- `#673` deterministic Morrowind pilot loop with world-state proof
- `#674` reflex tactical layer and semantic trajectory logging
- `#675` deterministic context compaction for long local sessions

## What gets preserved from legacy Matrix

High-value candidates include:
- visitor movement / embodiment
- chat, bark, and presence systems
- transcript logging
- ambient / visual atmosphere systems
- economy / satflow visualizations
- smoke and browser validation discipline

Those pieces should be carried forward only if they serve the mission and are re-tethered to real local system state.

## Running Locally

### Current repo truth

There is no root browser app on current `main`.
Do not tell people to static-serve the repo root and expect a world.

### Branch Protection & Review Policy

**All repositories enforce:**
- PRs required for all changes
- Minimum 1 approval required
- CI/CD must pass
- No force pushes
- No direct pushes to main

**Default reviewers:**
- `@perplexity` for all repositories
- `@Timmy` for nexus/ and hermes-agent/

**Enforced by Gitea branch protection rules**

### What you can run now

- `python3 server.py` for the local websocket bridge
- Python modules under `nexus/` for heartbeat / cognition work

### Browser world restoration path

The browser-facing Nexus must be rebuilt deliberately through the migration backlog above, using audited Matrix components and truthful validation.

---

*One 3D repo. One migration path. No more ghost worlds.*
# The Nexus Project

## Branch Protection Policy

We enforce the following rules on all `main` branches:

- Require PR for merge
- 1+ approvals required
- CI must pass
- Dismiss stale approvals
- Block force pushes
- Block branch deletion

Default reviewers:
- `@perplexity` (all repos)
- `@Timmy` (hermes-agent)

See [docus/branch-protection.md](docus/branch-protection.md) for full policy details
# Branch Protection & Review Policy

## Branch Protection Rules
- **Require Pull Request for Merge**: All changes must go through a PR.
- **Required Approvals**: At least one approval is required.
- **Dismiss Stale Approvals**: Approvals are dismissed on new commits.
- **Require CI to Pass**: CI must pass before merging (enabled where CI exists).
- **Block Force Push**: Prevents force-pushing to `main`.
- **Block Deletion**: Prevents deletion of the `main` branch.

## Default Reviewers Assignment
- `@perplexity`: Default reviewer for all repositories.
- `@Timmy`: Required reviewer for `hermes-agent` (owner gate).
- Repo-specific owners for specialized areas.
# Timmy Foundation Organization Policy

## Branch Protection & Review Requirements

All repositories must follow these rules for main branch protection:

1. **Require Pull Request for Merge** - All changes must go through PR process
2. **Minimum 1 Approval Required** - At least one reviewer must approve
3. **Dismiss Stale Approvals** - Approvals expire with new commits
4. **Require CI Success** - For hermes-agent only (CI runner #915)
5. **Block Force Push** - Prevent direct history rewriting
6. **Block Branch Deletion** - Prevent accidental main branch deletion

### Default Reviewers Assignments

- **All repositories**: @perplexity (QA gate)
- **hermes-agent**: @Timmy (owner gate)
- **Specialized areas**: Repo-specific owners for domain expertise

See [.github/CODEOWNERS](.github/CODEOWNERS) for specific file path review assignments.
# Contribution Policy

See [CONTRIBUTING.md](CONTRIBUTING.md) for full branch protection and review requirements.