Implementation Plan: Nx Workspace & Module Boundaries

Phase 3 Artifact — Establishes workspace enforcement per ENGINEERING.SOP.md Phase 3.

Purpose

Establish and continuously enforce the Nx workspace + module-boundary rules that implement the One Kernel, Multiple Shells topology and prevent accidental cross-context coupling. This plan is foundational and unblocks downstream plans by making “illegal imports” fail fast in CI and locally.

Pre-Flight Validation

STOP. Before implementing, validate all input specifications.

ADR Validation

PRD Validation

SDS Validation

Pipeline Verification

1
2
# This plan is workspace-level; no SEA-DSL compilation needed
just ci-quick  # Verify lint + specs pass

• Nx workspace compiles
• ESLint boundary rules configured

Provenance Chain

graph TD
    ADR33[ADR-033: Kernel-Shell Architecture] --> PRD23[PRD-023: SEA™ Platform Integration]
    ADR34[ADR-034: Nx Module Boundary Enforcement] --> PRD23
    ADR30[ADR-030: VibesPro™ Foundation Integration] --> PRD23
    PRD23 --> SDS48[SDS-048: Platform UI Integration]
    SDS48 --> C0A[C0A: Boundary Constraints]
    SDS48 --> C0D[C0D: Context Tagging]

    style ADR33 fill:#e1f5ff
    style ADR34 fill:#e1f5ff
    style ADR30 fill:#e1f5ff
    style PRD23 fill:#fff4e1
    style SDS48 fill:#e8f5e9

Implementation Order

Required sequence per ENGINEERING.SOP.md Phase 3.

1. Define architectural layers — Kernel (libs/sea/), Shells (apps/)
2. Enforce dependency constraints — ESLint @nx/enforce-module-boundaries
3. Introduce ports — All external interaction via port interfaces
4. Centralize contracts — libs/shared/contracts as shared types home
5. Validate enforcement — just ci-lint fails on violations

Proposed Cycles (Worktree-First)

Each cycle = one branch + one worktree. Waves enable parallel work.

Starting a Cycle

1
2
just cycle-start 0 0 A boundaries
cd ../SEA-p0-c0A

Wave 1 (Parallel)

• C0A: Normalize and lock boundary constraints
  • Worktree: ../SEA-p0-c0A
  • Implements: ADR-034 boundary enforcement
  • Satisfies: PRD-023 REQ-062, REQ-066
  • Files: eslint.config.js, nx.json
• C0B: Ensure documented Nx targets exist
  • Worktree: ../SEA-p0-c0B
  • Implements: Workspace ergonomics
  • Satisfies: PRD-023 REQ-066 (CI fails on violations)
  • Files: tools/nx/workspace/project.json, docs/reference/nx-targets.md
• C0C: Align affected codegen detection with spec paths
  • Worktree: ../SEA-p0-c0C
  • Implements: Deterministic regeneration
  • Files: tools/run_codegen_affected.sh

Wave 2 (Depends on Wave 1)

• C0D: Tag all libs and validate enforcement
  • Worktree: ../SEA-p0-c0D
  • Implements: ADR-033 topology, ADR-030 choke-point
  • Satisfies: PRD-023 REQ-060/062/066
  • Depends on: C0A (boundary rules must exist first)
  • Files: libs/**/project.json, **/src/gen/**

Worktree Lifecycle

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. Start cycle
just cycle-start 0 0 A boundaries
cd ../SEA-p0-c0A

# 2. Make changes
# Edit eslint.config.js, nx.json

# 3. Verify locally
just ci-lint
just ci-quick

# 4. Complete cycle
just cycle-complete 0 0 A
gh pr create --base dev

# 5. After merge, cleanup
cd ~/projects/SEA™
just cycle-worktree-remove 0 0 A

Nx Generators to Use

From develop-software.md § Generators.

1
2
3
4
5
# Context scaffolding
just generator-bc vibespro

# Adapter pair
just generator-adapter authz sea

Expected Filetree

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/
├── eslint.config.js                     # [C0A] Boundary constraints (ADR-034)
├── nx.json                              # [C0A] Workspace plugins/defaults
├── tools/
│   ├── nx/workspace/project.json        # [C0B] workspace targets
│   └── run_codegen_affected.sh          # [C0C] affected detection
├── libs/
│   ├── sea/                             # scope:sea (kernel)
│   │   ├── domain/                      # type:domain
│   │   ├── ports/                       # type:ports
│   │   ├── application/                 # type:application
│   │   └── adapters/                    # type:adapters
│   ├── vibespro/                        # scope:vibespro
│   │   └── public-api/                  # type:public-api (choke-point)
│   └── shared/                          # scope:shared
│       ├── contracts/                   # type:contracts
│       └── testing/                     # type:testing
└── apps/                                # type:shell

Validation & Verification

Pre-Merge Checks

• just ci passes (full local CI)
• just ci-lint fails on boundary violations
• nx run workspace:check exists and passes

Post-Implementation Verification

• Boundary violations fail lint: pnpm lint
• All libs have correct scope:* and type:* tags
• nx graph shows expected dependency structure
• Generated code remains in **/src/gen/** only

Dependencies Introduced

• No new dependencies — Uses existing Nx + ESLint

Risks & Mitigations

Rollback Strategy

1. Immediate: Revert enforcement changes (ESLint + Nx target wiring)
2. Fallback: Temporarily relax constraints to libs/sea/** only

Open Questions

1. tools/run_codegen_affected.sh watches specs/<ctx>/ but repo uses docs/specs/ — standardize paths? yes
2. Repo docs say workspace:check but code has codegen-affected — rename for consistency? yes
3. Tag policy for shells (type:shell) — where should apps live? yes

References

Do not duplicate content from these documents.

Linked Specifications