feat(jumentix): advance monorepo extraction, governance, and wave progress

.agents/README.md

@@ -61,6 +61,20 @@ Use these files as living constraints for future maintenance and feature develop
 - [044-pci-security-compliance-hardening](requirements/044-pci-security-compliance-hardening.md)
 - [045-data-entity-controller-ownership](requirements/045-data-entity-controller-ownership.md)
 - [046-multi-database-driver-smoke-validation](requirements/046-multi-database-driver-smoke-validation.md)
+- [047-realtime-api-test-matrix](requirements/047-realtime-api-test-matrix.md)
+- [048-jumentix-pnpm-monorepo-productization](requirements/048-jumentix-pnpm-monorepo-productization.md)
+- [049-jumentix-wave-execution-governance](requirements/049-jumentix-wave-execution-governance.md)
+- [050-generic-adapters-as-distributable-packages](requirements/050-generic-adapters-as-distributable-packages.md)
+- [051-runtime-bootstrap-shared-packages](requirements/051-runtime-bootstrap-shared-packages.md)
+- [052-rest-loader-framework-matrix](requirements/052-rest-loader-framework-matrix.md)
+- [053-jumentix-workspace-package-docs-and-ownership](requirements/053-jumentix-workspace-package-docs-and-ownership.md)
+- [054-sdk-compatibility-bridge-governance](requirements/054-sdk-compatibility-bridge-governance.md)
+- [055-wave5-app-rehoming-cutover-governance](requirements/055-wave5-app-rehoming-cutover-governance.md)
+- [056-jumentix-project-single-source-of-truth](requirements/056-jumentix-project-single-source-of-truth.md)
+- [057-pr-grouping-by-priority](requirements/057-pr-grouping-by-priority.md)
+- [058-jumentix-migration-inventory-and-rollback-governance](requirements/058-jumentix-migration-inventory-and-rollback-governance.md)
+- [059-jumentix-service-factory-and-deploy-template-matrices](requirements/059-jumentix-service-factory-and-deploy-template-matrices.md)
+- [060-jumentix-release-versioning-policy-governance](requirements/060-jumentix-release-versioning-policy-governance.md)
 - [Data Entity Documentation Agent](data-entity-documentation-agent.md)
 - [Domain Modeling Agent](domain-modeling-agent.md)
 - [Domain Designer Agent](domain-designer-agent.md)

.agents/integration-contracts-agent.md

@@ -14,6 +14,7 @@ Keep event/message contracts and error contracts explicit, synchronized, and enf
 - New error classes/codes/response shapes must be documented in `documentation/md/ERROR-CONTRACTS-AND-RESPONSES.md`.
 - Contract documentation and implementation must ship together.
 - Keep request/response envelope backward-compatible unless explicitly versioned.
+- Realtime contracts (`WebSocket`/`gRPC`) must maintain unit + integration + smoke coverage as defined in requirement `047`.
 
 ## Definition of done
 - Contract docs match current implementation.

.agents/requirements/047-realtime-api-test-matrix.md

@@ -0,0 +1,34 @@
+# Requirement 047 - Realtime API Test Matrix
+
+## Requirement
+
+Realtime APIs must have explicit automated validation at three levels:
+
+1. **Unit tests** for WebSocket and gRPC adapters/core runtime behavior.
+2. **Integration tests** for protocol-level request/response execution.
+3. **Smoke tests** for quick runtime health, including multi-instance Redis-backed validation where applicable.
+
+## Acceptance Criteria
+
+- Unit coverage exists for:
+  - `WebSocketAPI`
+  - `gRPCAPI`
+  - realtime bootstrap loaders
+  - adapter strategy modules (`cluster`, `redis-streams`)
+- Integration coverage exists for:
+  - basic WebSocket realtime flow
+  - basic gRPC realtime flow
+  - multi-instance Socket.IO + Redis Streams propagation
+- Smoke coverage exists for:
+  - local realtime protocol boot/response
+  - Redis-backed multi-instance command path
+- Scripts are available in `package.json` for all realtime test scopes.
+- Documentation is updated:
+  - `documentation/md/REALTIME-API-TESTING.md`
+  - README index links
+
+## Notes
+
+- Redis-backed integration should be environment-gated for CI/local portability (`RUN_REDIS_INTEGRATION=1`).
+- Realtime smoke/integration commands should run with `--coverage=false` to avoid coverage artifact drift.
+

.agents/requirements/048-jumentix-pnpm-monorepo-productization.md

@@ -0,0 +1,33 @@
+# Requirement 048 - JumentiX pnpm Monorepo Productization
+
+## Requirement
+
+`aaa-typescript-boilerplate` must evolve into the `JumentiX` product as a pnpm-managed monorepo.
+
+The monorepo must support:
+
+1. Product apps (`backend-template`, `service-management`).
+2. Publishable packages (`cli-init`, `message-mediator`, protocol SDKs, shared configs/contracts).
+3. Workspace-wide quality gates (lint, test, build, coverage, security).
+4. PM2 runtime management for multi-service backend/frontend execution.
+
+The migration must be executed in deterministic waves, with functional parity required before advancing each wave.
+
+## Acceptance Criteria
+
+- Workspace foundation exists and is functional:
+  - `pnpm-workspace.yaml`
+  - root scripts for recursive build/test/lint
+  - Node 22 enforced across workspace and CI
+- `message-mediator` is consumed as workspace package (not duplicated in backend app code).
+- SDK clients are split into independent publishable workspace packages.
+- CLI package is publish-ready and supports bootstrap orchestration for JumentiX project structures.
+- Existing backend capabilities remain available after move to `apps/backend-template`.
+- Service management remains functional under `apps/service-management`.
+- CI runs workspace-aware pipelines and preserves strict quality/coverage/security gates.
+- Product documentation and agents requirements are synchronized with monorepo structure.
+
+## Notes
+
+- Migration is wave-based and must avoid uncertain parallel rewrites.
+- No compatibility-shim strategy is required; prefer direct import rewrites with codemod-assisted changes and hard gates.

.agents/requirements/049-jumentix-wave-execution-governance.md

@@ -0,0 +1,27 @@
+# Requirement 049 - JumentiX Wave Execution Governance
+
+## Requirement
+
+JumentiX monorepo migration must be performed with deterministic, wave-based governance to reduce uncertain implementation and wasted effort.
+
+Each wave must define:
+
+1. Explicit scope.
+2. Deliverables.
+3. Acceptance criteria.
+4. Rollback point.
+5. Quality gates required before proceeding.
+
+## Acceptance Criteria
+
+- A centralized execution plan exists and is maintained:
+  - `documentation/md/JUMENTIX-MONOREPO-EXECUTION-PLAN.md`
+- `project-todos` includes the operational wave checklist.
+- Each migration wave only advances when:
+  - build/test/lint/coverage/security checks are green
+  - docs and agents are synchronized
+- No multi-wave mixed PRs unless explicitly justified by dependency constraints.
+
+## Notes
+
+- This requirement is process and governance oriented and complements the technical monorepo requirement.

.agents/requirements/050-generic-adapters-as-distributable-packages.md

@@ -0,0 +1,22 @@
+# Requirement 050 - Generic Adapters as Distributable npm Packages
+
+## Requirement
+
+Any adapter that is generic and reusable across multiple services must be extracted as a distributable npm package.
+
+The adapter must not remain duplicated inside each generated service codebase when it can be consumed as a shared package.
+
+## Acceptance Criteria
+
+- Reusable adapters are implemented under workspace packages and prepared for npm distribution.
+- Service code imports reusable adapters/contracts from workspace packages instead of local duplicated implementations.
+- Local legacy files (when kept temporarily) must be thin re-exports only, to avoid behavior drift.
+- Package-level documentation exists describing:
+  - purpose
+  - supported runtimes/providers
+  - integration usage
+- Migration wave todos and requirements registry are updated when a new reusable adapter is packaged.
+
+## Notes
+
+- `@jumentix/message-mediator` is the reference implementation pattern.

.agents/requirements/051-runtime-bootstrap-shared-packages.md

@@ -0,0 +1,19 @@
+# 051 - Runtime Bootstrap Shared Packages
+
+## Context
+
+As part of JumentiX monorepo productization, adapter bootstrapping must avoid repeated wiring logic across HTTP, WebSocket, and gRPC startup files.
+
+## Requirement
+
+1. Runtime bootstrap concerns must be centralized into reusable workspace packages:
+   - infra selection by env (`database`, `key-value`, `mutex`)
+   - adapter composition (`jwt`, `crypto`, `message mediator`, `auth service`)
+2. Interface adapters must consume shared bootstrap compilers rather than duplicating wiring logic.
+3. Existing adapter entrypoints must remain backward compatible while migration happens.
+
+## Acceptance Criteria
+
+- Shared packages are created and used by adapter entrypoints.
+- Core adapter bootstrap tests remain green.
+- No change in runtime contract for existing startup commands.

.agents/requirements/052-rest-loader-framework-matrix.md

@@ -0,0 +1,17 @@
+# 052 - REST Loader Framework Matrix
+
+## Context
+
+REST startup was previously split across many direct framework entrypoints, increasing coupling between scripts and adapter implementation files.
+
+## Requirement
+
+1. `start-rest-api` must support selecting all implemented HTTP frameworks via `AAA_HTTP_FRAMEWORK`.
+2. Environment and PM2 startup scripts should prefer loader entrypoints over direct framework file execution.
+3. Default behavior must remain backward compatible (`express` when no env is provided).
+
+## Acceptance Criteria
+
+- `resolveHTTPFramework` recognizes the full framework set.
+- `start-rest-api` resolves and imports the framework adapter based on env.
+- Unit tests cover at least express + one non-express framework path, plus unsupported values.

.agents/requirements/053-jumentix-workspace-package-docs-and-ownership.md

@@ -0,0 +1,18 @@
+# Requirement 053 - JumentiX Workspace Package Docs and Ownership
+
+## Context
+
+During monorepo migration, each workspace package must have explicit ownership and usage documentation to reduce ambiguity and avoid duplicate implementations.
+
+## Requirement
+
+1. Every new workspace package must include a package-level `README.md`.
+2. Root documentation must include a workspace package catalog.
+3. CLI and SDK packages must document command/API usage examples.
+4. Backlog (`.agents/project-todos.md`) must reflect wave progress for package readiness.
+
+## Acceptance criteria
+
+- Package READMEs exist for `@jumentix/cli-init`, `@jumentix/sdk-rest-client`, `@jumentix/sdk-websocket-client`, and `@jumentix/sdk-grpc-client`.
+- Root README links to workspace package catalog.
+- `documentation/md/JUMENTIX-WORKSPACE-PACKAGES.md` exists and is synchronized with current packages.

.agents/requirements/054-sdk-compatibility-bridge-governance.md

@@ -0,0 +1,18 @@
+# Requirement 054 - SDK Compatibility Bridge Governance
+
+## Context
+
+During Wave 3 migration, SDK ownership moved to `packages/sdk-*`, but legacy imports under `sdk-clients/*` still exist.
+
+## Requirement
+
+1. `sdk-clients/*` must remain a pure compatibility layer (re-exports only).
+2. New SDK implementation code must live only under `packages/sdk-*`.
+3. Bridge behavior and removal criteria must be explicitly documented.
+4. README index must link the bridge documentation.
+
+## Acceptance criteria
+
+- `sdk-clients/*` files contain only package re-exports and bridge aggregator.
+- `documentation/md/SDK-COMPATIBILITY-BRIDGE.md` exists.
+- Root README links to bridge documentation.

.agents/requirements/055-task-traceability-commit-pr-association.md

@@ -0,0 +1,27 @@
+# Requirement 055 - Task Traceability (Commit + PR Association)
+
+## Context
+
+To keep GitHub Project tasks auditable and reduce execution ambiguity, every task (issue) must include explicit engineering traceability metadata.
+
+## Requirement
+
+For **all project tasks** (open or closed), maintain:
+
+1. `PR` reference (URL or `#number`)
+2. `Commit` reference (single commit hash or commit range)
+
+At minimum, each task update must include:
+
+- PR linkage to the delivery stream
+- commit linkage to implementation evidence
+
+## Operational Rule
+
+- Before closing a task, verify commit + PR references are present in issue comments or issue body.
+- For active tasks not yet implemented, maintain a placeholder traceability update pointing to the active delivery PR and current commit baseline.
+
+## Acceptance Criteria
+
+- All issues under project tracking label (`todo-mvp`) have commit + PR linkage visible.
+- New task updates follow the same traceability format.

.agents/requirements/055-wave5-app-rehoming-cutover-governance.md

@@ -0,0 +1,18 @@
+# Requirement 055 - Wave 5 App Re-homing Cutover Governance
+
+## Context
+
+Wave 5 moves runtime applications into workspace app boundaries. Without a strict cutover guide, path regressions and CI breakages become highly likely.
+
+## Requirement
+
+1. App re-homing must follow a documented step-by-step cutover sequence.
+2. PM2 paths and runtime adapters must be validated after every move step.
+3. Rollback instructions must be explicit and reversible by wave scope.
+4. Final acceptance criteria must include CI gates and coverage policy compliance.
+
+## Acceptance criteria
+
+- `documentation/md/JUMENTIX-WAVE5-APP-REHOMING-CUTOVER.md` exists and is referenced by the execution plan and README index.
+- `.agents/project-todos.md` Wave 5 progress references the cutover document.
+- No Wave 5 PR is considered done without green CI gates and coverage threshold compliance.

.agents/requirements/056-jumentix-project-single-source-of-truth.md

@@ -0,0 +1,25 @@
+# Requirement 056 - Jumentix Project Single Source of Truth
+
+## Context
+
+Project execution must be managed from one authoritative tracking system to avoid drift between local TODO files and delivery state.
+
+## Requirement
+
+1. GitHub Project `Jumentix` (`https://github.com/users/web2solutions/projects/1`) is the single source of truth for bugs and new features.
+2. Every task must exist as an issue and be added to the project.
+3. Required project fields must be maintained for active tasks:
+   - Status
+   - Priority
+   - Size
+   - Estimate
+   - Start date
+   - End date
+4. Every PR must include issue and project-item linkage details.
+5. Documentation must remain synchronized with this governance model.
+
+## Acceptance criteria
+
+- Project governance doc exists and is linked in docs index.
+- PR templates require project and issue linkage.
+- Contributing guidance requires project item tracking.

.agents/requirements/057-pr-grouping-by-priority.md

@@ -0,0 +1,18 @@
+# Requirement 057 - PR Grouping by Priority
+
+## Context
+
+To improve review quality and delivery predictability, pull requests must be grouped by priority level.
+
+## Requirement
+
+1. PRs must be scoped by a single priority group (`P0`, `P1`, or `P2`).
+2. Mixing tasks from different priority groups in one PR is not allowed.
+3. PR templates must require explicit declaration of priority group.
+4. Project item links must confirm the selected priority group.
+
+## Acceptance criteria
+
+- PR templates contain mandatory priority-group field.
+- Governance docs define priority-group PR policy.
+- Delivery workflow follows `P0` first, then `P1`, then `P2`.

.agents/requirements/058-jumentix-migration-inventory-and-rollback-governance.md

@@ -0,0 +1,18 @@
+# Requirement 058 - JumentiX Migration Inventory and Rollback Governance
+
+## Context
+
+Monorepo migration requires deterministic execution, low-risk rollback, and explicit path ownership mapping to avoid uncertain implementation cycles.
+
+## Requirement
+
+1. Keep a canonical migration inventory mapping current root paths to target `apps/*` and `packages/*`.
+2. Define branch, release tag, and rollback strategy per migration wave.
+3. Keep scope split explicit between Wave 1 (must-have parity) and Wave 2+ enhancements.
+4. Keep this governance synchronized with project TODO and execution plan docs.
+
+## Implementation references
+
+- `documentation/md/JUMENTIX-MIGRATION-INVENTORY-AND-ROLLBACK.md`
+- `documentation/md/JUMENTIX-MONOREPO-EXECUTION-PLAN.md`
+- `.agents/project-todos.md`

.agents/requirements/059-jumentix-service-factory-and-deploy-template-matrices.md

@@ -0,0 +1,34 @@
+# Requirement 059 - JumentiX Service Factory and Deploy Template Matrices
+
+## Context
+
+JumentiX productization requires explicit planning contracts for:
+
+- service factory capability modes
+- deploy target and packaging contracts
+- bundler/runtime templates by artifact type
+
+## Requirement
+
+The project must maintain documented, indexed, and current matrix artifacts that define:
+
+1. Service factory modes:
+   - modular monolith backend
+   - multi-service backend
+   - hybrid backend + frontend
+   - frontend-only SPA/PWA offline
+2. Deploy target and packaging contracts:
+   - VM/SSH, EC2/VM cloud, Lambda, Vercel Functions, Cloudflare Workers
+   - required metadata contracts for Service Management
+3. Bundler/runtime templates by artifact type:
+   - backend service
+   - frontend SPA
+   - frontend SSR
+   - backend npm library
+   - frontend npm library
+
+## Enforcement
+
+- README documentation index must include links to all three matrix documents.
+- `.agents/project-todos.md` must track these planning deliverables as complete/open with progress notes.
+- Any change in runtime/deploy/factory model must update matrix docs and this requirement if contract scope changes.

.agents/requirements/060-jumentix-release-versioning-policy-governance.md

@@ -0,0 +1,25 @@
+# Requirement 060 - JumentiX Release and Versioning Policy Governance
+
+## Context
+
+JumentiX monorepo needs a deterministic release/version policy to avoid drift across apps/packages and keep CI release checks reliable.
+
+## Requirement
+
+- The canonical policy file `release-policy.json` must exist at repository root.
+- Policy model:
+  - `packages/*` follow independent versioning.
+  - `apps/*` follow locked versioning tied to root `package.json` version.
+- Release governance checks must fail CI when policy or metadata contracts are violated.
+
+## Enforcement
+
+- `npm run release:governance:check` is mandatory and included in `npm run ci:gate`.
+- App workspaces must be `private: true` and their `version` must match `release-policy.json.appLockedVersion`.
+- Publishable packages must have valid semver and non-empty `files` metadata.
+- Root release scripts (`changelog:*`, `release:dry-run*`) must remain present.
+
+## Documentation Sync
+
+- Keep `documentation/md/JUMENTIX-RELEASE-AND-VERSIONING-STRATEGY.md` updated.
+- Keep README Documentation Index linked to the release strategy document.