bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
learning_ai_common_plat/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md
saravanakumardb1 f18134c719 docs: align ecosystem docs with single-source-of-truth agent pattern 
Followup to single-source-of-truth migration. Active docs that taught or
described the old 8-file agent-config pattern are updated to reflect the
new architecture.

- docs/ECOSYSTEM_CONSISTENCY_AUDIT.md: update §7 Agent Documentation,
  resolve F19 (ActionTrail missing CLAUDE.md) and F20 (Auth App missing
  agent docs) — both eliminated by the migration. Update §9 consistency
  checklist with new file inventory (AGENTS.md + canonical pointer,
  thin copilot pointer, legacy files removed across all 17 active repos).

- docs/learning_ai_common_plat_INVENTORY.md: replace deleted
  AI.dev/SKILLS/update-agent-docs.md with agent-behavior-guidelines.md
  and agent-onboarding.md entries. Add check-agent-docs-drift.sh to the
  scripts table.

- docs/guides/PLATFORM_PLAYBOOK.md: update new-product scaffold tree to
  show the 4 canonical files (AGENTS.md + 3 auto-generated derivatives),
  drop CLAUDE.md/.cursorrules/.windsurfrules.

- docs/guides/PLATFORM_ACCELERATION_IDEAS.md: update create-app CLI
  description to reference the canonical pointer + derived files.

- docs/guides/WORKFLOW_SYNC.md: clarify what /repo_update-agent-docs does.

Historical/completed roadmaps in docs/roadmaps/completed/ are left as-is —
they accurately describe state at the time and editing them would rewrite
history.
2026-05-23 12:07:58 -07:00

325 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ByteLyst Ecosystem Consistency Audit
> **Date:** 2026-03-21
> **Scope:** All 13 repos in the ByteLyst workspace
> **Auditor:** Cascade AI
---
## 1. Product Identity (`shared/product.json`)
### Port Allocation (no collisions ✅)
| Product | Port | Repo |
| ------------------ | ---- | ----------------------------------- |
| PeakPulse | 4010 | `learning_ai_peakpulse` |
| ChronoMind | 4011 | `learning_ai_clock` |
| JarvisJr | 4012 | `learning_ai_jarvis_jr` |
| NomGap | 4013 | `learning_ai_fastgap` |
| MindLyst | 4014 | `learning_multimodal_memory_agents` |
| LysnrAI | 4015 | `learning_voice_ai_agent` |
| NoteLett | 4016 | `learning_ai_notes` |
| FlowMonk | 4017 | `learning_ai_flowmonk` |
| ActionTrail | 4018 | `learning_ai_trails` |
| LocalMemGPT | 4019 | `learning_ai_local_memory_gpt` |
| Platform-service | 4003 | `learning_ai_common_plat` |
| Extraction-service | 4005 | `learning_ai_common_plat` |
| MCP-server | 4007 | `learning_ai_common_plat` |
### Schema Consistency
**Full schema (16 fields):** MindLyst, ChronoMind, JarvisJr, PeakPulse — ✅ consistent
**Newer schema (10 fields, uses `bundleIds` + `tagline` + `appStore`):** FlowMonk, ActionTrail, LocalMemGPT, SmartAuth — ✅ consistent among themselves
| Finding | Severity | Repos |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- |
| **F1: NomGap product.json minimal** — only 4 fields (`productId`, `displayName`, `bundleId`, `domain`), missing `backendPort`, `version`, `licensePrefix`, `configDirName`, `envVarPrefix`, `packageName` | 🟡 Medium | `learning_ai_fastgap` |
| **F2: LysnrAI product.json missing domain/backendPort** — only 7 fields, no `domain`, `backendPort`, `description`, `cosmos`, `platforms`, `primarySurface` | 🟡 Medium | `learning_voice_ai_agent` |
| **F3: NoteLett hybrid schema** — mixes old (`bundleIdSuffix`, `packageName`) and new (`backendPort`, `domain`) but missing `version`, `cosmos`, `platforms` | 🟡 Medium | `learning_ai_notes` |
| **F4: ByteLyst Auth uses `productName` instead of `displayName`** | 🟠 Low | `learning_ai_auth_app` |
| **F5: Two schema patterns** — older repos use `bundleId` (object), newer use `bundleIds` (object). Not a bug but inconsistent. | 🟢 Info | — |
---
## 2. Backend Patterns (Fastify 5 + TypeScript ESM)
### Shared Package Adoption
All 10 product backends have:
- ✅ `@bytelyst/auth` — JWT utilities
- ✅ `@bytelyst/config` — env loader + product identity
- ✅ `@bytelyst/datastore` — Cosmos/memory abstraction
- ✅ `@bytelyst/errors` — typed HTTP errors
- ✅ `@bytelyst/fastify-core` — createServiceApp() factory
- ✅ `@bytelyst/fastify-auth` — auth middleware
- ✅ `@bytelyst/backend-config` — backend config helpers
- ✅ `@bytelyst/backend-flags` — feature flag server-side
- ✅ `@bytelyst/backend-telemetry` — telemetry buffer
- ✅ `product-config.ts` in `src/lib/` — all 10 backends
### Fastify Version
| Version | Repos |
| -------- | ---------------------------------------------------------- |
| `^5.2.1` | LysnrAI, MindLyst, ChronoMind, JarvisJr, NomGap, PeakPulse |
| `5.7.4` | FlowMonk, ActionTrail, LocalMemGPT |
| `^5.2.1` | NoteLett |
| Finding | Severity |
| ------------------------------------------------------------------------------------------ | --------- |
| **F6: Fastify version split** — 6 repos on `^5.2.1`, 3 on `5.7.4`. Should align to latest. | 🟡 Medium |
### Field Encryption
| Finding | Severity |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| **F7: LocalMemGPT missing @bytelyst/field-encrypt** — uses local AES-256-GCM instead of shared package. Intentional (SQLite-based, local-first app) but divergent. | 🟢 Info |
All other 9 Cosmos-based backends have `@bytelyst/field-encrypt` ✅
### Advanced Packages (SSE, Events, Webhooks)
Only FlowMonk and ActionTrail have:
- `@bytelyst/fastify-sse` — SSE streaming
- `@bytelyst/event-store` — domain event persistence
- `@bytelyst/webhook-dispatch` — outbound webhook delivery
LocalMemGPT has `@bytelyst/fastify-sse` and `@bytelyst/llm-router` (unique).
Other backends may need these as they mature — not a gap yet.
---
## 3. Web Frontend Patterns
### Next.js + React Versions
| Version | Repos |
| ----------------------------------- | ---------------------------------------------------- |
| Next.js 16.1.6 + React 19.2.3 | LysnrAI, ChronoMind, JarvisJr, FlowMonk, ActionTrail |
| Next.js 16.1.6 + React 19.2.0 | NomGap, NoteLett |
| Next.js ^16.0.0 + React ^19.0.0 | MindLyst |
| **Next.js ^15.3.2 + React ^19.1.0** | **LocalMemGPT** |
| Finding | Severity |
| ---------------------------------------------------------------------------------- | -------- |
| **F8: LocalMemGPT on Next.js 15** — all other repos on Next.js 16. Should upgrade. | 🟠 High |
### TailwindCSS
| Status | Repos |
| --------------------------- | -------------------------------------------------- |
| TailwindCSS v4 ✅ | LysnrAI, ChronoMind, NomGap, NoteLett, LocalMemGPT |
| **Missing TailwindCSS** | **MindLyst, FlowMonk, ActionTrail** |
| TailwindCSS v4 via JarvisJr | JarvisJr ✅ |
| Finding | Severity |
| ---------------------------------------------------------------------------------------------------------------------------- | --------- |
| **F9: MindLyst uses vanilla CSS** — `--ml-*` props in `globals.css`, no Tailwind. Intentional per AGENTS.md ("NO Tailwind"). | 🟢 Info |
| **F10: FlowMonk + ActionTrail missing TailwindCSS** — use inline styles or basic CSS. Should add for consistency. | 🟡 Medium |
### CSS Custom Property Namespaces
| Namespace | Product | Status |
| -------------------- | ------------ | ------ |
| `--cm-*` | ChronoMind | ✅ |
| `--jj-*` | JarvisJr | ✅ |
| `--ng-*` | NomGap | ✅ |
| `--ml-*` | MindLyst | ✅ |
| `--fm-*` | FlowMonk | ✅ |
| `--at-*` | ActionTrail | ✅ |
| `--lmg-*` | LocalMemGPT | ✅ |
| **`--nl-*` MISSING** | **NoteLett** | ❌ |
| Finding | Severity |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **F11: NoteLett globals.css has no `--nl-*` custom properties** — contrary to AGENTS.md which says "Theme tokens use `--nl-*` CSS custom properties". | 🟠 High |
### Web Auth Pattern (`@bytelyst/react-auth`)
| Has `react-auth` in web deps | Has `auth.ts` using it |
| ---------------------------- | --------------------------------------------------- |
| LysnrAI ✅ | LysnrAI uses custom auth-server pattern (dashboard) |
| ChronoMind ✅ | ChronoMind uses auth-client directly |
| NomGap ✅ | NomGap ✅ `auth.ts` uses `react-auth` |
| NoteLett ✅ | NoteLett ✅ `auth.ts` uses `react-auth` |
| ActionTrail ✅ | ActionTrail ✅ `auth.ts` uses `react-auth` |
| JarvisJr ❌ | JarvisJr — no `react-auth` dep |
| FlowMonk ❌ | FlowMonk — no `react-auth` dep |
| LocalMemGPT ❌ | LocalMemGPT — auth is optional (local-first) |
| Finding | Severity |
| -------------------------------------------------------------------------------------------------------- | --------- |
| **F12: JarvisJr web missing `@bytelyst/react-auth`** — has kill-switch + telemetry but no auth provider. | 🟡 Medium |
| **F13: FlowMonk web missing `@bytelyst/react-auth`** — no auth provider in web. | 🟡 Medium |
### Web `product-config.ts`
| Finding | Severity |
| ----------------------------------------------------------------------------- | --------- |
| **F14: ChronoMind web missing `product-config.ts`** — all other webs have it. | 🟡 Medium |
---
## 4. Mobile / Native Patterns
### iOS Platform SDK (`Platform/` directory)
| App | Platform/ dir | Status |
| ---------- | ------------------------------------------------------ | ------------------------------------- |
| LysnrAI | `mobile_app/ios/LysnrAI/Platform/` | ✅ |
| MindLyst | `mindlyst-native/iosApp/Platform/` | ✅ |
| ChronoMind | `ios/ChronoMind/Shared/Cloud/` + `Shared/Diagnostics/` | ⚠️ Different (valid for multi-target) |
| JarvisJr | `ios/JarvisJr/Platform/` | ✅ |
| PeakPulse | `ios/PeakPulse/Platform/` | ✅ |
### Android Kotlin Platform SDK
All 3 Android apps (ChronoMind, MindLyst, LysnrAI) have `includeBuild` for `kotlin-platform-sdk` ✅
JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SDK needed).
---
## 5. Design Tokens
`@bytelyst/design-tokens` generates:
- `tokens.css` — web CSS vars
- `tokens.ts` — TypeScript constants
- `MindLystTokens.kt` — Android tokens
- `MindLystTheme.swift` — iOS tokens
| Finding | Severity |
| ------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **F15: Only 3 webs import `@bytelyst/design-tokens`** — LysnrAI, NomGap, NoteLett. Other webs define CSS custom props manually. | 🟡 Medium |
---
## 6. CI/CD & Docker
### GitHub Actions
| Status | Repos |
| --------------- | ------------------------------------------------------------------------------------- |
| Active `ci.yml` | ChronoMind, JarvisJr, NomGap, PeakPulse, FlowMonk, NoteLett, ActionTrail, LocalMemGPT |
| Disabled | LysnrAI (`disabled.yml`), MindLyst (`disabled.yml`) |
| No CI | ByteLyst Auth App |
| Finding | Severity |
| --------------------------------------------------------------------------------------------------------- | --------- |
| **F16: LysnrAI + MindLyst CI disabled** — mature repos with extensive test suites should have CI enabled. | 🟡 Medium |
| **F17: ByteLyst Auth App has no CI** — no `.github/workflows/` at all. | 🟡 Medium |
### Docker
| Has docker-compose + Dockerfiles | Repos |
| ---------------------------------------- | ------------------------------------------------------- |
| ✅ Full stack | NomGap, NoteLett, ActionTrail, LocalMemGPT |
| docker-compose only (references sibling) | LysnrAI |
| **No Docker** | **MindLyst, ChronoMind, JarvisJr, PeakPulse, FlowMonk** |
| Finding | Severity |
| --------------------------------------------------------------------------- | -------- |
| **F18: 5 repos have no Docker configs** — makes local/CI deployment harder. | 🟢 Info |
---
## 7. Agent Documentation
> **Migrated (May 2026) to single-source-of-truth pattern.** Behavior rules
> live in one canonical file:
> `learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`.
> Per-repo `AGENTS.md` references it via an auto-managed pointer block.
> Legacy files (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`)
> have been deleted across all repos — they duplicated AGENTS.md content and
> drifted.
### File Presence Matrix (post-migration)
| File | Present (of 17 active) | Notes |
| --------------------------------- | ---------------------- | ------------------------------------------- |
| `AGENTS.md` | 17/17 ✅ | Hand-maintained; canonical pointer prepended |
| `.github/copilot-instructions.md` | 17/17 ✅ | Thin pointer, auto-generated |
| `.aider.conf.yml` | 17/17 ✅ | Aider config, auto-generated |
| `.editorconfig` | 17/17 ✅ | Auto-generated |
| `CLAUDE.md` | 0/17 ✅ | **Deprecated** (deleted) |
| `.cursorrules` | 0/17 ✅ | **Deprecated** (deleted) |
| `.windsurfrules` | 0/17 ✅ | **Deprecated** (deleted) |
| `.clinerules` | 0/17 ✅ | **Deprecated** (deleted) |
F19 and F20 are now **resolved** by the migration — ActionTrail and ByteLyst
Auth App no longer need the legacy files. Drift is enforced via
`scripts/check-agent-docs-drift.sh`.
| Finding | Status |
| -------------------------------------------------------------------------- | --------------------- |
| ~~F19: ActionTrail missing CLAUDE.md~~ | ✅ Resolved (deleted) |
| ~~F20: ByteLyst Auth App missing CLAUDE.md, .windsurfrules, .cursorrules~~ | ✅ Resolved (deleted) |
---
## 8. Summary Scorecard
### Critical (should fix now)
| # | Finding | Fix |
| --- | ----------------------------------------------- | ---------------------------------------- |
| F8 | LocalMemGPT on Next.js 15 | Upgrade to Next.js 16 |
| F11 | NoteLett missing `--nl-*` CSS custom properties | Add design token CSS vars to globals.css |
### Medium (should fix soon)
| # | Finding | Fix |
| --- | ----------------------------------------------- | ---------------------------------------------- |
| F1 | NomGap product.json minimal (4 fields) | Add missing fields to match ecosystem standard |
| F2 | LysnrAI product.json missing domain/backendPort | Add missing fields |
| F3 | NoteLett product.json hybrid schema | Normalize to ecosystem standard |
| F6 | Fastify version split (^5.2.1 vs 5.7.4) | Align all to latest 5.7.x |
| F10 | FlowMonk + ActionTrail missing TailwindCSS | Add TailwindCSS v4 |
| F12 | JarvisJr web missing @bytelyst/react-auth | Add auth provider |
| F13 | FlowMonk web missing @bytelyst/react-auth | Add auth provider |
| F14 | ChronoMind web missing product-config.ts | Create product-config.ts |
| F15 | Only 3 webs import @bytelyst/design-tokens | Add to remaining webs |
| F16 | LysnrAI + MindLyst CI disabled | Re-enable ci.yml |
| ~~F20~~ | ByteLyst Auth App missing agent docs | ✅ Resolved by single-source migration |
### Low / Informational
| # | Finding | Notes |
| --- | ---------------------------------------------------- | ------------------------------------------- |
| F4 | Auth App uses `productName` instead of `displayName` | Minor schema inconsistency |
| F5 | Two bundleId schema patterns | `bundleId` (object) vs `bundleIds` (object) |
| F7 | LocalMemGPT uses local encryption | Intentional — SQLite-based local-first app |
| F9 | MindLyst no Tailwind | Intentional per AGENTS.md |
| F17 | Auth App no CI | Minimal repo, mostly native |
| F18 | 5 repos no Docker | Not all repos need containerization yet |
| ~~F19~~ | ActionTrail missing CLAUDE.md | ✅ Resolved by single-source migration |
---
## 9. Ecosystem-Wide Consistency Checklist
| Dimension | Status |
| --------------------------------- | ------------------------------------------------ |
| Product ID in Cosmos docs | ✅ All backends enforce `productId` |
| Port allocation (no collisions) | ✅ 4010–4019 + 4003/4005/4007 |
| Backend Fastify 5 | ✅ All 10 backends |
| Backend `@bytelyst/fastify-core` | ✅ All 10 backends |
| Backend `@bytelyst/field-encrypt` | ✅ 9/10 (LocalMemGPT intentionally different) |
| Backend `product-config.ts` | ✅ All 10 backends |
| Web Next.js 16 | ⚠️ 8/9 (LocalMemGPT on 15) |
| Web CSS namespace `--XX-*` | ⚠️ 7/8 (NoteLett missing) |
| Web `@bytelyst/react-auth` | ⚠️ 5/8 applicable webs |
| Web `product-config.ts` | ⚠️ 7/8 (ChronoMind missing) |
| iOS `Platform/` directory | ✅ 4/5 (ChronoMind valid alternative) |
| Android kotlin-platform-sdk | ✅ All 3 Android apps |
| `AGENTS.md` + canonical pointer | ✅ 17/17 |
| `.github/copilot-instructions.md` | ✅ 17/17 (thin pointer, auto-generated) |
| Legacy agent files removed | ✅ 17/17 (CLAUDE.md, .cursorrules, .windsurfrules, .clinerules) |
| GitHub Actions CI | ⚠️ 8/12 active |
| `shared/product.json` | ⚠️ Inconsistent schemas across older/newer repos |
Reference in New Issue View Git Blame Copy Permalink