Eve library

phase-14.md

Tracker

Revision 1

On this page

Historical task source. The Eve task board holds current task state.

Phase 14: Documentation & Cleanup#

14.1 Architecture Documentation ✅#

  • 14.1.1 Create ARCHITECTURE.md at oshun root
  • 14.1.2 Document domain responsibilities
  • 14.1.3 Create architecture diagrams
  • 14.1.4 Document data ownership matrix
  • 14.1.5 Document event flows

14.2 API Documentation ✅#

  • 14.2.1 Generate OpenAPI docs for each domain
  • 14.2.2 Set up unified API documentation site
  • 14.2.3 Add SDK usage examples
  • 14.2.4 Document authentication flows

14.3 Developer Guides#

  • 14.3.1 Create getting started guide for monorepo
  • 14.3.2 Create guide for adding new services
  • 14.3.3 Create guide for adding new libraries
  • 14.3.4 Create guide for cross-domain integration
  • 14.3.5 Document Nx commands and workflows

14.4 Migration Guides#

  • 14.4.1 Create migration guide for Lilith developers
  • 14.4.2 Create migration guide for Yemaya developers
  • 14.4.3 Document breaking changes
  • 14.4.4 Create FAQ for common migration issues

14.5 README Updates#

  • 14.5.1 Create oshun/README.md with monorepo overview
  • 14.5.2 Update README for each domain
  • 14.5.3 Add badges for CI status, coverage, etc.
  • 14.5.4 Add quick start instructions

14.6 Cleanup#

  • 14.6.1 Remove empty directories
  • 14.6.2 Remove unused configuration files
  • 14.6.3 Remove deprecated code
  • 14.6.4 Clean up TODO comments
  • 14.6.5 Run final lint and format

14.7 Final Validation#

  • 14.7.1 Build the affected projects clean. Restated 2026-09-18: nx run-many --target=build --all (1729 projects) is banned in a worktree per CLAUDE.md and thrashes the 15 GB box. Instead confirm the repo's build CI is green on main (the per-project affected graph run by .github/workflows/ci.yml / oshun-ci.yml), and fix each failing touched project with its own npx nx build <project> or npx tsc --noEmit. The prior revert was due to real Isis build failures — those must be fixed. Verify: the build job is green on main at a named SHA, recorded here.
  • 14.7.2 Test the affected projects clean. Restated 2026-09-18: replace nx run-many --target=test --all with the affected-graph test job in CI, fixing each failing touched project with npx vitest run <path>. Verify: the test job is green on main at a named SHA.
  • 14.7.3 Lint the affected projects clean. Restated 2026-09-18: replace nx run-many --target=lint --all with the affected-graph lint job in CI, fixing each failing touched project with npx eslint <path>. Verify: the lint job is green on main at a named SHA.
  • 14.7.4 Verify all Docker builds succeed
    • Docker infrastructure verified working locally
    • Base image build (docker/Dockerfile.node) succeeds
    • container-build.yml workflow configured for CI/CD
    • Affected apps built via: pnpm nx show projects --affected --type=app --with-target=container
  • 14.7.5 Deploy to staging environment. Withdrawn 2026-09-18: this phase's Kubernetes/ArgoCD staging cut-over is superseded — deployment is now the single-box Hetzner compose plane (deploy-hetzner.yml), and this documentation/cleanup phase's migration finished in spring 2026.
  • 14.7.6 Run smoke tests in staging. Withdrawn 2026-09-18: depended on 14.7.5; the Hetzner deploy workflow runs its own public smoke step.
  • 14.7.7 Document any remaining issues
    • Original notes (resolved): Isis Anthropic SDK type compatibility, Isis Prisma client generation. Verified passing on current branch.
    • Original notes (still in effect): ESLint plugin excludes apps/** due to flat-config compatibility; broad lint cleanup pending.
    • Backlog from this session (open items in 14.7.1):
      • The 2026-04-23 fail-fast full build gate still fails. Observed failure batches include @hathor/veilborn-core, @lilith/real-time-sync, @lilith/data-governance, @lilith/teacher-blessing, @lilith/group-meditation, @lilith/daily-content, @lilith/staking-mechanism, @lilith/catalog, @lilith/blockchain, @lilith/notification, and @lilith/progress-sync.
      • bellona-sdk-cpp requires system cmake install.
      • @lilith/service-lib has ~10+ TS errors (mock surface drift, verbatimModuleSyntax type-only imports, consent-purpose narrowing) — needs surgical per-file fixes.
      • End-to-end build/test/lint sweep across all 1900+ Nx projects not yet executed; expect additional individual project failures to surface, each needing focused remediation.

14.8 Release#

  • 14.8.1 Create release branch. Withdrawn 2026-09-18: “Phase 14 release” is a migration that finished in spring 2026; the live release train is V1.0 (libs/oshun/navigation/src/release-scope.ts), not a phase-14 cut.
  • 14.8.2 Update version numbers. Withdrawn 2026-09-18: part of the finished phase-14 migration release; superseded by the V1.0 release train.
  • 14.8.3 Generate changelog. Withdrawn 2026-09-18: same as 14.8.1.
  • 14.8.4 Create release tag. Withdrawn 2026-09-18: same as 14.8.1.
  • 14.8.5 Deploy to production. Withdrawn 2026-09-18: production deploy is the Hetzner deploy-hetzner.yml approve-production path, not a phase-14 step.
  • 14.8.6 Monitor production metrics. Withdrawn 2026-09-18: production monitoring is the Hetzner observability plane (infra/hetzner/observability), not a phase-14 step.
  • 14.8.7 Announce migration completion. Withdrawn 2026-09-18: the phase-14 migration finished in spring 2026; there is no pending migration to announce.

Summary Statistics#

Phase Task Count
Phase 0: Pre-Migration Setup 17
Phase 1: Repository & Package Manager 21
Phase 2: Nx Workspace Initialization 43
Phase 3: Shared Foundation Libraries 60
Phase 4: Contracts & Schema Layer 38
Phase 5: Isis (Generative Factory) 72
Phase 6: Sophia (Research & Knowledge) 58
Phase 7: Hathor (Worldbuilding & Narrative) 62
Phase 8: Bellona (Engine & Build/Bridge) 92
Phase 9: Yemaya (Creative Studio) 87
Phase 10: Lilith (Consciousness Experience) 96
Phase 11: Cross-Domain Integration 31
Phase 12: CI/CD & DevOps 52
Phase 13: Testing & Validation 31
Phase 14: Documentation & Cleanup 36
TOTAL 796

Dependency Order#

The phases should generally be executed in order, but some can be parallelized:

  1. Phase 0 must complete first
  2. Phase 1-2 must be sequential
  3. Phase 3-4 must complete before domain phases
  4. Phases 5-8 (capability domains) can be parallelized
  5. Phases 9-10 (product domains) can be parallelized after 5-8
  6. Phase 11 requires 5-10 to be substantially complete
  7. Phases 12-14 can overlap with later parts of 5-11

Notes#

  • Tasks marked with (RECOMMEND:) indicate the recommended approach per the recommendation document
  • Some tasks may be skipped if not applicable to your specific needs
  • Time estimates are intentionally omitted - focus on sequential completion
  • This checklist can be tracked via GitHub issues or project management tools
  • Consider creating GitHub milestones for each phase