the-nexus/CONTRIBUTING.md

Contributing to the Nexus

Every PR: net ≤ 10 added lines. Not a guideline — a hard limit. Add 40, remove 30. Can't remove? You're homebrewing. Import instead.

Why

Import over invent. Plug in the research. No builder trap. Removal is a first-class contribution. Baseline: 4,462 lines (2026-03-25). Goes down.

PR Checklist

1. Net diff ≤ 10 (+12 -8 = net +4 ✅ / +200 -0 = net +200 ❌)
2. Manual test plan — specific steps, not "it works"
3. Automated test output — paste it, or write a test (counts toward your 10)

Applies to every contributor: human, Timmy, Claude, Perplexity, Gemini, Kimi, Grok. Exception: initial dependency config files (requirements.txt, package.json). No other exceptions. Too big? Break it up.

Reviewer Policy

Every PR must have a reviewer assigned before merge. See docs/pr-reviewer-policy.md.

Contribution and Code Review Policy

Branch Protection Rules

All repositories must enforce the following rules on the main branch:

• ✅ Require Pull Request for merge
• ✅ Require 1 approval before merge
• ✅ Dismiss stale approvals when new commits are pushed
• ✅ Require status checks to pass (where CI is configured)
• ✅ Block force-pushing to main
• ✅ Block deleting the main branch

Default Reviewer Assignment

All repositories must configure the following default reviewers:

• @perplexity as default reviewer for all repositories
• @Timmy as required reviewer for hermes-agent
• Repo-specific owners for specialized areas

Implementation Status

Repository	Branch Protection	CI Enforcement	Default Reviewers
hermes-agent	✅ Enabled	✅ Active	@perplexity, @Timmy
the-nexus	✅ Enabled	⚠️ CI pending	@perplexity
timmy-home	✅ Enabled	❌ No CI	@perplexity
timmy-config	✅ Enabled	❌ No CI	@perplexity

Compliance Requirements

All contributors must:

1. Never push directly to main
2. Create a pull request for all changes
3. Get at least one approval before merging
4. Ensure CI passes before merging (where applicable)

Policy Enforcement

This policy is enforced via Gitea branch protection rules. Violations will be blocked at the platform level.

For questions about this policy, contact @perplexity or @Timmy.

Required for All Merges

• Pull Request must exist for all changes
• At least 1 approval from reviewer
• CI checks must pass (where applicable)
• No force pushes allowed
• No direct pushes to main
• No branch deletion

Review Requirements

• @perplexity must be assigned as reviewer
• @Timmy must review all changes to hermes-agent/
• No self-approvals allowed

CI/CD Enforcement

• CI must be configured for all new features
• Failing CI blocks merge
• CI status displayed in PR header

Abandoned PR Policy

• PRs inactive >7 days get "needs attention" label
• PRs inactive >21 days are archived
• PRs inactive >90 days are closed
• At least 1 approval from reviewer
• CI checks must pass (where available)
• No force pushes allowed
• No direct pushes to main
• No branch deletion

Review Requirements by Repository

hermes-agent:
  required_owners:
    - perplexity
    - Timmy

the-nexus:
  required_owners:
    - perplexity

timmy-home:
  required_owners:
    - perplexity

timmy-config:
  required_owners:
    - perplexity

CI Status

- hermes-agent: ✅ Active
- the-nexus: ⚠️ CI runner disabled (see #915)
- timmy-home: - (No CI)
- timmy-config: - (Limited CI)

Branch Protection Status

All repositories now enforce:

• Require PR for merge
• 1+ approvals required
• CI/CD must pass (where applicable)
• Force push and branch deletion blocked
• hermes-agent: ✅ Active
• the-nexus: ⚠️ CI runner disabled (see #915)
• timmy-home: - (No CI)
• timmy-config: - (Limited CI)

## Workflow
1. Create feature branch
2. Open PR against main
3. Get 1+ approvals
4. Ensure CI passes
5. Merge via UI

## Enforcement
These rules are enforced by Gitea branch protection settings. Direct pushes to main will be blocked.

## Abandoned PRs
PRs not updated in >7 days will be labeled "stale" and may be closed after 30 days of inactivity.
# Contributing to the Nexus

**Every PR: net ≤ 10 added lines.** Not a guideline — a hard limit.
Add 40, remove 30. Can't remove? You're homebrewing. Import instead.

## Branch Protection & Review Policy

### Branch Protection Rules

All repositories enforce the following rules on the `main` branch:

| Rule | Status | Applies To |
|------|--------|------------|
| Require Pull Request for merge | ✅ Enabled | All |
| Require 1 approval before merge | ✅ Enabled | All |
| Dismiss stale approvals on new commits | ✅ Enabled | All |
| Require CI to pass (where CI exists) | ⚠️ Conditional | All |
| Block force pushes to `main` | ✅ Enabled | All |
| Block deletion of `main` branch | ✅ Enabled | All |

### Default Reviewer Assignments

| Repository | Required Reviewers |
|------------|------------------|
| `hermes-agent` | `@perplexity`, `@Timmy` |
| `the-nexus` | `@perplexity` |
| `timmy-home` | `@perplexity` |
| `timmy-config` | `@perplexity` |

### CI Enforcement Status

| Repository | CI Status |
|------------|-----------|
| `hermes-agent` | ✅ Active |
| `the-nexus` | ⚠️ CI runner pending (#915) |
| `timmy-home` | ❌ No CI |
| `timmy-config` | ❌ Limited CI |

### Review Requirements

- All PRs must be reviewed by at least one reviewer
- `@perplexity` is the default reviewer for all repositories
- `@Timmy` is a required reviewer for `hermes-agent`

All repositories enforce:
- ✅ Require Pull Request for merge
- ✅ Require 1 approval
- ⚠<> Require CI to pass (CI runner pending)
- ✅ Dismiss stale approvals on new commits
- ✅ Block force pushes
- ✅ Block branch deletion

## Review Requirements

- Mandatory reviewer: `@perplexity` for all repos
- Mandatory reviewer: `@Timmy` for `hermes-agent/`
- Optional: Add repo-specific owners for specialized areas

## Implementation Status

- ✅ hermes-agent: All protections enabled
- ✅ the-nexus: PR + 1 approval enforced
- ✅ timmy-home: PR + 1 approval enforced
- ✅ timmy-config: PR + 1 approval enforced

> CI enforcement pending runner restoration (#915)

## 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

README.md

<<<<<<< SEARCH