This document exists to provide context for any developer, AI assistant, or future maintainer working on this code base. It captures the architectural reasoning behind the project's design choices so that intelligence can be added at the right layer, in the right way, at the right time.
The document was written and based off a personal project (homelab-registry-mcp) but the knowledge should serve as guidance as Nexus reaches a production-ready state.
- Created `nexus-work-item-register.md` to establish a canonical registry for NEXUS-XXX work items, including shard assignments and a full work item backlog.
- Added `READ_ONLY_VERIFICATION.md` detailing the results of a security audit confirming zero write capabilities across integrated systems.
- Introduced `RESILIENCE.md` outlining the new enterprise system resilience feature, including automatic retry logic, circuit breaker pattern, and graceful degradation strategies.
- Developed `TEST_VALIDATION_REPORT.md` summarizing the successful rebuild of the Nexus MCP server with full audit shard functionality and comprehensive test results.
- Updated Nexus MCP Tool Inventory with new NEXUS references and improved tool descriptions.
- Added comprehensive README.md for Nexus MCP, detailing architecture, folder structure, and tool references.
- Introduced RESILIENCE.md to document the new enterprise system resilience features, including automatic retry logic and circuit breaker patterns.
- Created TEST_VALIDATION_REPORT.md summarizing test results and server capabilities post-rebuild.
- Established a canonical work item register (nexus-work-item-register.md) to track NEXUS-XXX work items and their statuses.
- Updated scripts to reflect changes in work item references from WIS to NEXUS.
- Update prompt model frontmatter in code-review and feature-add prompts to Claude Sonnet 4.6 (copilot)
- Add a save_report implementation plan prompt to support next-session delivery and clearer handoff context
- Update prompt model frontmatter in code-review and feature-add prompts to Claude Sonnet 4.6 (copilot)
- Add a save_report implementation plan prompt to support next-session delivery and clearer handoff context
- Move setup docs into documentation/ and remove legacy MCP troubleshooting content and ad hoc probe files
- Support the session goal of a cleaner, gated workflow with clearer restart context and less maintenance noise
- Add scripts/update_readme_status.py to generate a deterministic status block, enforce traffic-light shard tables, and validate/fix internal links
- Refactor nexus-mcp/README.md into a managed status layout with standardized WIS traceability and Discipline Drives Quality sections
- Aligns with session goals for operational readiness and disciplined documentation as Nexus-MCP scales
Ref: SESSION_SNAPSHOT_2026-04-13
- Remove generated package outputs from nexus-mcp/dist/*.whl and *.tar.gz
- Remove generated metadata from nexus-mcp/src/nexus_mcp.egg-info/*
- Keep repository source-only and rely on local/CI builds for artifacts
- Update nexus-mcp/pyproject.toml to register the integration pytest marker and keep test execution policy explicit
- Regenerate package metadata and distribution artifacts in nexus-mcp/src/nexus_mcp.egg-info/* and nexus-mcp/dist/*
Ref: Session Snapshot 2026-04-13 — close out pending pytest validation hygiene
- Add conftest.py to inject lib/ onto sys.path, fixing
ModuleNotFoundError on identity test collection
- Add pytest-asyncio to CI install step and pyproject.toml
test extras; set asyncio_mode=auto to resolve 31 async
test failures flagged in session tech debt backlog
- All 35 tests now pass; 8 skipped (live API, expected)
Ref: Session Snapshot 2026-04-13 — "Pytest validation incomplete"
- Implement 4 production-ready audit scan tools in src/shards/audit.py
- scan_status_reconciliation: detect terminated users still enabled in AD
- scan_job_title_drift: detect title mismatches between Workday and AD
- scan_department_mismatches: detect department/cost center drift
- scan_name_variance_mismatches: detect display name inconsistencies
- Add comprehensive integration test suite (tests/integration_test_audit_shard.py)
- Create demo client (test_client.py) and MCP protocol simulator (test_mcp_protocol.py)
- Add tool catalog generator (list_tools.py) for visibility across all 33 registered tools
- Fix Windows console encoding in src/main.py to support emoji in shard status output
- Add version management utility (scripts/bump_version.py) for release automation
- Update workday test imports to use new drift_detection module path
Completes session goal of establishing SOC 2-compliant cross-system drift detection
per SESSION_SNAPSHOT_2026-04-13.md. All audit tools validated against mock data
with expected mismatch scenarios (Bob Martinez, Carol Chen, David Kim cases).
Refs: WIS-014, WIS-015, WIS-016, WIS-017, WIS-018
- nexus-mcp/src/shards/audit.py: Replaced corrupted file (unterminated triple-quoted strings, Unicode encoding issues with em dashes) with minimal working stub
- nexus-mcp/src/shards/audit.py.fresh: Backup of previous corrupted version from git history
- nexus-mcp/src/shards/audit_minimal.py: Alternative version with client imports for future expansion
- egg-info metadata: Added from `pip install -e .` installation in isolated venv
Resolves server startup failure where Python parser could not handle malformed docstrings in original audit.py. The previous committed version (fe77b0f) contained syntax errors that prevented initialization of the audit shard. This minimal stub allows nexus-mcp orchestrator to load and register all 5 working shards successfully.
Ref: Server initialization restored - all shards loading (identity, workday, itsm, assets, logistics, audit)
- Fixed resilient_http_call decorator to NOT retry on 4xx client errors (only 5xx)
- Changed retry condition from retry_if_exception_type to retry_if_exception with custom logic
- Updated datetime.utcnow() to datetime.now(UTC) to fix deprecation warnings
- Fixed test imports to add lib/ to sys.path
All 12 unit tests now pass with no warnings.
Addresses technical debt where data objects (User, Worker, Device) were using
fragile dict access patterns instead of validated pydantic models.
- Add nexus-mcp/lib/schemas.py: Canonical domain models (CanonicalUser, CanonicalDevice,
FieldDrift) with automatic field normalization and validation
- Add nexus-mcp/lib/adapters.py: System-specific adapters (ADUserAdapter, EntraUserAdapter,
WorkdayWorkerAdapter) to transform native API responses into canonical format
- Update identity.py: ad_get_user, ad_search_users, entra_list_users now return
normalized CanonicalUser objects with consistent field names
- Update workday.py: workday_list_workers, workday_get_worker return canonical format
for seamless cross-system comparison
- Update audit.py: Refactor audit_user_drift to use type-safe _compare_users() helper
with FieldDrift schema instead of manual dict comparisons
Benefits:
• Type safety: IDE autocomplete, runtime validation, eliminates fragile _pick() calls
• Consistent field names: user.job_title works across AD/Entra/Workday (was 3 different paths)
• Automatic validation: Email normalization, status enum enforcement
• Drift detection: Validated Bob Martinez title mismatch (AD "Sr. Software Engineer"
vs Workday "Software Engineer")
Ref: Session goal "implement atomic, piece-at-a-time shard deployment capability"
requiring robust data contracts between systems.
- Move Identity/, Workday/, Intune/ to archive/ (superseded by nexus-mcp shards)
- Move 'Local Setup.md' to archive/ (superseded by nexus-mcp/Local-Setup.md)
- Add archive/README.md explaining migration and preserved content
- Clean repository structure: only nexus-mcp, documentation, and .github remain active
All legacy functionality migrated to nexus-mcp sharded architecture.
Archived folders preserved for reference and historical context.
Refs: SESSION_SNAPSHOT_2026-04-13.md
- Add SESSION_SNAPSHOT_2026-04-03 with goals, accomplishments, and pending work
- Document next-session startup steps for Workday-to-AD sync delivery continuity
Expand README with repository intent, active Workday-to-AD sync workflow goals, and key document links.
Capture current session context as a dated progress snapshot (completed, in-progress, and next milestones); no SESSION_SNAPSHOT file was found in documentation/project-history.
- Add execution planning artifacts in workday-ad-identity-sync-next-steps.md and workday-ad-identity-sync-sprint-board.md.
- Capture the why from current staged context by turning identified Workday sync blockers and delivery sequencing into a prioritized backlog and sprint-ready board; no SESSION_SNAPSHOT file was found in documentation/project-history for additional session intent.
- Add [FrankGPT consolidated instructions](.github/agents/FrankGPT.consolidated-instructions.md) and supporting standards in [.github/instructions/core.instructions.md](.github/instructions/core.instructions.md) to define agent modes, commands, and workflows.
- Expand prompt and knowledge assets, including [.github/prompts/create-commit.msg.prompt.md](.github/prompts/create-commit.msg.prompt.md), to standardize ITIL-aligned reasoning and improve session-aware commit/message generation.
nathan