[nexus] docs(01-02): create zone taxonomy, rebase runbook, and hook installer
- Add .planning/ZONE-TAXONOMY.md classifying all rename targets (DISPLAY/CODE/STORED) - Add .planning/REBASE-RUNBOOK.md documenting range-diff rebase verification workflow - Add scripts/install-hooks.sh for post-clone hook reinstallation
This commit is contained in:
Nexus Dev
parent
3db6bdfc3c
commit
960db7b1cd
3 changed files with 166 additions and 0 deletions
83
.planning/REBASE-RUNBOOK.md
Normal file
83
.planning/REBASE-RUNBOOK.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# Nexus Rebase Runbook
|
||||
|
||||
Step-by-step workflow for rebasing Nexus fork commits onto new upstream Paperclip releases.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `git rerere` enabled: `git config rerere.enabled true`
|
||||
- `git range-diff` available (git 2.19+, confirmed 2.39.5 on this machine)
|
||||
- Upstream remote configured: `git remote add upstream https://github.com/paperclipai/paperclip.git` (if not already)
|
||||
|
||||
## Pre-Rebase Checklist
|
||||
|
||||
1. Ensure working tree is clean: `git status`
|
||||
2. Fetch upstream: `git fetch upstream`
|
||||
3. Record current tip: `git log --oneline -1` (save this SHA as OLD_TIP)
|
||||
4. Verify all tests pass before rebase: `pnpm test:run`
|
||||
|
||||
## Rebase Procedure
|
||||
|
||||
```bash
|
||||
# 1. Fetch latest upstream
|
||||
git fetch upstream
|
||||
|
||||
# 2. Rebase nexus commits onto upstream/master
|
||||
git rebase upstream/master
|
||||
|
||||
# 3. If conflicts arise:
|
||||
# - git rerere will auto-apply previously recorded resolutions
|
||||
# - For new conflicts: resolve manually, then `git add` + `git rebase --continue`
|
||||
# - rerere automatically records new resolutions for future use
|
||||
|
||||
# 4. Verify rebase integrity with range-diff
|
||||
# ORIG_HEAD is the pre-rebase tip (set automatically by git)
|
||||
git range-diff upstream/master ORIG_HEAD HEAD
|
||||
```
|
||||
|
||||
## Post-Rebase Verification
|
||||
|
||||
1. **range-diff check:** `git range-diff upstream/master ORIG_HEAD HEAD`
|
||||
- Every nexus commit should show as "equivalent" (minor offset changes only)
|
||||
- Flag any commit showing significant diff changes for manual review
|
||||
2. **Test suite:** `pnpm test:run` — all tests must pass
|
||||
3. **Type check:** `pnpm typecheck` (if available) or `pnpm -r run typecheck`
|
||||
4. **Branding spot check:** `pnpm vitest run --project packages/branding`
|
||||
|
||||
## Handling Common Scenarios
|
||||
|
||||
### Upstream changed a file we also changed (DISPLAY zone)
|
||||
- Most common: string changes in UI components
|
||||
- rerere should handle if previously resolved
|
||||
- If new: resolve keeping Nexus display string, `git add`, continue
|
||||
|
||||
### Upstream added new constants to packages/shared/src/constants.ts
|
||||
- Our changes are in `packages/branding/` (separate file) — no conflict expected
|
||||
- If AGENT_ROLE_LABELS format changes upstream, update the DISPLAY zone mapping
|
||||
|
||||
### Upstream restructured a file entirely
|
||||
- range-diff will show the affected nexus commit as "changed"
|
||||
- Manually verify the nexus change still applies correctly
|
||||
- Update zone taxonomy if file paths changed
|
||||
|
||||
## rerere Cache Notes
|
||||
|
||||
- Cache lives in `.git/rr-cache/` (not tracked by git)
|
||||
- Cache is machine-local — lost on re-clone
|
||||
- After a fresh clone, first rebase may require manual resolution
|
||||
- Subsequent rebases at the same conflict points will auto-resolve
|
||||
|
||||
## Hook Re-installation
|
||||
|
||||
After a fresh clone, the commit-msg hook must be reinstalled:
|
||||
|
||||
```bash
|
||||
# From repo root:
|
||||
cp scripts/nexus-commit-msg-hook.sh .git/hooks/commit-msg
|
||||
chmod +x .git/hooks/commit-msg
|
||||
```
|
||||
|
||||
Or using the install script:
|
||||
|
||||
```bash
|
||||
bash scripts/install-hooks.sh
|
||||
```
|
||||
77
.planning/ZONE-TAXONOMY.md
Normal file
77
.planning/ZONE-TAXONOMY.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Nexus Zone Taxonomy
|
||||
|
||||
Classifies every Paperclip-to-Nexus rename target by zone.
|
||||
Zones determine which occurrences are safe to change and which must stay unchanged for upstream sync.
|
||||
|
||||
**Zones:**
|
||||
- **DISPLAY** — User-facing strings safe to rename (UI text, banners, tooltips, help text, button labels)
|
||||
- **CODE** — TypeScript identifiers, import paths, route segments, env vars — do NOT touch
|
||||
- **STORED** — DB column/table names, stored enum values — do NOT touch
|
||||
|
||||
---
|
||||
|
||||
## DISPLAY Zone (safe to change in Phases 2-4)
|
||||
|
||||
| Target | Location | Current Value | Nexus Value | Phase |
|
||||
|--------|----------|---------------|-------------|-------|
|
||||
| Company display string in JSX | ~16 UI files in `ui/src/` | "Company" | "Workspace" | 3 |
|
||||
| Companies plural in JSX | UI files | "Companies" | "Workspaces" | 3 |
|
||||
| CEO display string in JSX | `ui/src/components/agent-config-primitives.tsx`, `AgentProperties.tsx`, etc. | "CEO" | "Project Manager" | 3 |
|
||||
| Board display string in JSX | Various UI files | "Board" | "Owner" | 3 |
|
||||
| Hire button text | UI dialogs | "Hire" | "Add" | 3 |
|
||||
| Fire button text | UI dialogs | "Fire" | "Remove" | 3 |
|
||||
| `AGENT_ROLE_LABELS.ceo` value | `packages/shared/src/constants.ts` | `"CEO"` | `"Project Manager"` | 2 |
|
||||
| PAPERCLIP ASCII banner | `server/src/startup-banner.ts` | "PAPERCLIP" | "NEXUS" | 2 |
|
||||
| PAPERCLIP ASCII banner (CLI) | `cli/src/utils/banner.ts` | "PAPERCLIP" | "NEXUS" | 2 |
|
||||
| App title in browser tab | `ui/index.html` or layout | "Paperclip" | "Nexus" | 3 |
|
||||
| Top-left logo text | UI layout component | "Paperclip" | "Nexus" | 3 |
|
||||
| CLI help text brand name | `cli/src/` command descriptions | "Paperclip" | "Nexus" | 3 |
|
||||
| paperclip.ing URL references | `ui/src/pages/CompanyExport.tsx` | "paperclip.ing" | Nexus URL | 3 |
|
||||
| Favicon and logo assets | `ui/public/` or assets dir | Paperclip branding | Nexus branding | 3 |
|
||||
|
||||
---
|
||||
|
||||
## CODE Zone (do NOT touch — upstream sync priority)
|
||||
|
||||
| Target | Location | Rationale |
|
||||
|--------|----------|-----------|
|
||||
| `companyService`, `companyId`, `selectedCompanyId` | Throughout server/ui/cli | TypeScript identifiers — hundreds of import references |
|
||||
| `companies` table name | `packages/db/src/schema/` | DB table — migration required to rename |
|
||||
| `company_id` FK columns | `packages/db/src/schema/` | DB columns — migration required |
|
||||
| `/api/companies` route segment | `server/src/routes/companies.ts` | API contract — client/server must match |
|
||||
| `COMPANY_STATUSES` / `CompanyStatus` type | `packages/shared/src/constants.ts` | Upstream shared type — plugin API contract |
|
||||
| `@paperclipai/*` package names | All `package.json` files | Import paths throughout monorepo |
|
||||
| `PAPERCLIP_*` env vars | Server/CLI config | Breaks existing deployments |
|
||||
| `board_api_keys` table / `board` actor type | DB schema, auth code | Auth token format, DB schema |
|
||||
| `pcp_board_*` token prefixes | Auth code | Would invalidate issued tokens |
|
||||
| `.paperclip.yaml` export format | Import/export code | Upstream compatibility |
|
||||
|
||||
---
|
||||
|
||||
## STORED Zone (do NOT touch — DB integrity)
|
||||
|
||||
| Target | Location | Stored Where | Rationale |
|
||||
|--------|----------|-------------|-----------|
|
||||
| `"ceo"` in `AGENT_ROLES` | `packages/shared/src/constants.ts` | `agent_role` DB column | Existing rows contain this value |
|
||||
| `"hire_agent"` approval type | `packages/shared/src/constants.ts` APPROVAL_TYPES | `approval_type` DB column | Existing approvals reference this |
|
||||
| `"approve_ceo_strategy"` | `packages/shared/src/constants.ts` APPROVAL_TYPES | `approval_type` DB column | Existing approvals reference this |
|
||||
| `"bootstrap_ceo"` invite type | `packages/shared/src/constants.ts` | `invite_type` DB column | Existing invites reference this |
|
||||
| `company_id` FK values | All FK columns | PostgreSQL foreign keys | Data integrity constraint |
|
||||
|
||||
---
|
||||
|
||||
## Zone Summary
|
||||
|
||||
| Zone | Count | Rule |
|
||||
|------|-------|------|
|
||||
| DISPLAY | ~40 surface points | Safe to rename in Phases 2-4 |
|
||||
| CODE | Many hundreds | Never rename — upstream sync priority |
|
||||
| STORED | ~8 enum/column values | Never rename — DB integrity |
|
||||
|
||||
---
|
||||
|
||||
## Decision Rule
|
||||
|
||||
When the same term appears in multiple zones (e.g., "ceo" is both STORED as `AGENT_ROLES[0]` and DISPLAY as `AGENT_ROLE_LABELS.ceo` value), classify each occurrence independently. The key stays, only the display value changes.
|
||||
|
||||
**Example:** `AGENT_ROLES` contains `"ceo"` (STORED — do not touch). `AGENT_ROLE_LABELS.ceo` has value `"CEO"` (DISPLAY — safe to change to `"Project Manager"`). Both live in the same file (`packages/shared/src/constants.ts`), but the treatment differs per occurrence.
|
||||
6
scripts/install-hooks.sh
Normal file
6
scripts/install-hooks.sh
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
#!/bin/sh
|
||||
# Install Nexus git hooks
|
||||
REPO_ROOT="$(git rev-parse --show-toplevel)"
|
||||
cp "$REPO_ROOT/scripts/nexus-commit-msg-hook.sh" "$REPO_ROOT/.git/hooks/commit-msg"
|
||||
chmod +x "$REPO_ROOT/.git/hooks/commit-msg"
|
||||
echo "Nexus commit-msg hook installed."
|
||||
Loading…
Add table
Reference in a new issue