From 3a76d5f972ecccb8352ca1fed52ca4dbe35342b5 Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Mon, 30 Mar 2026 22:32:41 +0200 Subject: [PATCH] [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 --- .planning/REBASE-RUNBOOK.md | 83 +++++++++++++++++++++++++++++++++++++ .planning/ZONE-TAXONOMY.md | 77 ++++++++++++++++++++++++++++++++++ scripts/install-hooks.sh | 6 +++ 3 files changed, 166 insertions(+) create mode 100644 .planning/REBASE-RUNBOOK.md create mode 100644 .planning/ZONE-TAXONOMY.md create mode 100644 scripts/install-hooks.sh diff --git a/.planning/REBASE-RUNBOOK.md b/.planning/REBASE-RUNBOOK.md new file mode 100644 index 00000000..454c2475 --- /dev/null +++ b/.planning/REBASE-RUNBOOK.md @@ -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 +``` diff --git a/.planning/ZONE-TAXONOMY.md b/.planning/ZONE-TAXONOMY.md new file mode 100644 index 00000000..e054d1f2 --- /dev/null +++ b/.planning/ZONE-TAXONOMY.md @@ -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. diff --git a/scripts/install-hooks.sh b/scripts/install-hooks.sh new file mode 100644 index 00000000..d7687c57 --- /dev/null +++ b/scripts/install-hooks.sh @@ -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."