Mikkel Georgsen
3a76d5f972
- 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
4.5 KiB
4.5 KiB
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.