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

**All PRs must:**
- Have at least 1 approval
- Pass CI (where available)
- Be reviewed by @perplexity (QA gate)
- Be reviewed by @Timmy for `hermes-agent/` changes

Branch protection rules enforce:
- No direct pushes to `main`
- No merges without approval
- No merges with failing CI
- No force pushes or branch deletions

See [branch protection policy](README.md#branch-protection-rules) for full details.
# 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
- [x] Pull Request must exist for all changes
- [x] At least 1 approval from reviewer
- [x] CI checks must pass (where applicable)
- [x] No force pushes allowed
- [x] No direct pushes to main
- [x] No branch deletion

### Review Requirements
- [x] @perplexity must be assigned as reviewer
- [x] @Timmy must review all changes to `hermes-agent/`
- [x] No self-approvals allowed

### CI/CD Enforcement
- [x] CI must be configured for all new features
- [x] Failing CI blocks merge
- [x] 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
```yaml
hermes-agent:
  required_owners:
    - perplexity
    - Timmy

the-nexus:
  required_owners:
    - perplexity

timmy-home:
  required_owners:
    - perplexity

timmy-config:
  required_owners:
    - perplexity
```

### CI Status

```text
- 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
# Contribution & Code Review Policy

## Branch Protection Rules (Enforced via Gitea)
All repositories must have the following branch protection rules enabled on the `main` branch:

1. **Require Pull Request for Merge**  
   - Prevent direct commits to `main`
   - All changes must go through PR process

# Contribution & Code Review Policy

## Branch Protection Rules
All repositories enforce:
- ✅ Require Pull Request for merge
- ✅ Minimum 1 approval required
- ✅ Dismiss stale approvals on new commits
- ⚠️ Require CI to pass (CI runner pending for the-nexus)
- ✅ Block force push to `main`
- ✅ Block deletion of `main` branch

## Review Requirement
- 🧑‍ Default reviewer: `@perplexity` (QA gate)
- 🧑 Required reviewer: `@Timmy` for `hermes-agent/` only

## Workflow
1. Create feature branch from `main`
2. Submit PR with clear description
3. Wait for @perplexity review
4. Address feedback if any
5. Merge after approval and passing CI

## CI/CD Requirements
- All main branch merge require:
  - ✅ Linting
  - ✅ Unit tests
  - ⚠️ Integration tests (pending for the-nexus)
  - ✅ Security scans

## Exceptions
- Emergency hotfixes require:
  - ✅ @Timmy approval
  - ✅ Post-merge documentation
  - ✅ Follow-up PR for full review

## Abandoned PRs
- PRs inactive >7 days: 🧹 archived
- Unreviewed PRs >14 days: ❌ closed

## CI Status
- ✅ hermes-agent: CI active
- <20>️ the-nexus: CI runner dead (see #915)
- ✅ timmy-home: No CI
- <20>️ timmy-config: Limited CI
>>>>>>> replace
```

CODEOWNERS
```text
<<<<<<< search
# Contribution & Code Review Policy

## Branch Protection Rules
All repositories must:
- ✅ Require PR for merge
- ✅ Require 1 approval
- ✅ Dismiss stale approvals
- ⚠️ Require CI to pass (where exists)
- ✅ Block force push
- ✅ block branch deletion

## Review Requirements
- 🧑 Default reviewer: `@perplexity` for all repos
- 🧑 Required reviewer: `@Timmy` for `hermes-agent/`

## Workflow
1. Create feature branch from `main`
2. Submit PR with clear description
3. Wait for @perplexity review
4. Address feedback if any
5. Merge after approval and passing CI

## CI/CD Requirements
- All main branch merges require:
  - ✅ Linting
  - ✅ Unit tests
  - ⚠️ Integration tests (pending for the-nexus)
  - ✅ Security scans

## Exceptions
- Emergency hotfixes require:
  - ✅ @Timmy approval
  - ✅ Post-merge documentation
  - ✅ Follow-up PR for full review

## Abandoned PRs
- PRs inactive >7 days: 🧹 archived
- Unreviewed PRs >14 days: ❌ closed

## CI Status
- ✅ hermes-agent: ci active
- ⚠️ the-nexus: ci runner dead (see #915)
- ✅ timmy-home: No ci
- ⚠️ timmy-config: Limited ci