Mikkel Georgsen
890cb52954
- 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
77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
# 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.
|