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 onmain(the per-project affected graph run by.github/workflows/ci.yml/oshun-ci.yml), and fix each failing touched project with its ownnpx nx build <project>ornpx tsc --noEmit. The prior revert was due to real Isis build failures — those must be fixed. Verify: the build job is green onmainat a named SHA, recorded here. - 14.7.2 Test the affected projects clean. Restated 2026-09-18: replace
nx run-many --target=test --allwith the affected-graph test job in CI, fixing each failing touched project withnpx vitest run <path>. Verify: the test job is green onmainat a named SHA. - 14.7.3 Lint the affected projects clean. Restated 2026-09-18: replace
nx run-many --target=lint --allwith the affected-graph lint job in CI, fixing each failing touched project withnpx eslint <path>. Verify: the lint job is green onmainat 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-cpprequires systemcmakeinstall.@lilith/service-libhas ~10+ TS errors (mock surface drift,verbatimModuleSyntaxtype-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.
- The 2026-04-23 fail-fast full build gate still fails. Observed failure
batches include
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.ymlapprove-productionpath, 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:
- Phase 0 must complete first
- Phase 1-2 must be sequential
- Phase 3-4 must complete before domain phases
- Phases 5-8 (capability domains) can be parallelized
- Phases 9-10 (product domains) can be parallelized after 5-8
- Phase 11 requires 5-10 to be substantially complete
- 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