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.
WORKDAY_WORKERS (9 workers, was 8):
- Add v6 fields to every worker: firstName, lastName, legalName,
preferredName, primaryWorkPhone, effectiveDate, employeeID,
primaryJob.manager ref, supervisoryOrganization, costCenter
- Add WORKDAY_WORKERS_BY_ID lookup index
- Add Taylor Brooks (WD-EMP-1009, Terminated) — new highest-severity drift
AD_USERS (9 users, was 7):
- Add Henry Park (EMP-1008, disabled/514) — new hire not yet provisioned
- Add Taylor Brooks (EMP-1009, enabled/512) — terminated but AD still active
- Seed Grace Lee title drift: AD 'Human Resources Director' vs Workday 'HR Director'
- Seed Frank Davis dept drift: AD 'Information Technology' vs Workday 'IT Operations'
- Normalize Emma/Grace AD dept to 'Human Resources' (remove unintentional mismatch)
WORKDAY_WORKERS (Emma Wilson):
- Set legalName='Emma Thompson' (name change) — triggers scan_name_variance
drift_detection.py:
- Add _build_workers_from_mock_data() — bridges WORKDAY_WORKERS + AD_USERS
into the flat worker schema the scan functions consume
- MOCK_WORKERS_FROM_MOCK_DATA: built at import time; default for all scans
- Refactor all 4 scan functions with optional workers= param (default=None
uses MOCK_WORKERS_FROM_MOCK_DATA; legacy MOCK_WORKERS constant preserved)
Scan results (USE_MOCK=true):
scan_status_reconciliation 1 HIGH (Taylor Brooks — terminated/enabled)
scan_job_title_mismatches 2 MEDIUM (Bob, Grace)
scan_department_drift 2 MEDIUM (Carol, Frank)
scan_name_variance 1 LOW (Emma — name change not synced to AD)
Refs: feat/enrich-workday-mock-data | Q2 live-data integration prep
- document production-correct AD dual-account and privileged OU handling
- record policy-aware identity confidence implementation status
- capture explainability improvements in identity output semantics
- note Entra admin-consent as external blocker with clean handoff next steps
- ad_adapter.py: emit snake_case keys from PS queries and surface
email via the `mail` attribute in both get_user and search paths
- adapters.py: update ADUserAdapter.to_canonical to consume
normalized keys (e.g. `username`, `last_logon_utc`, `ou`) instead
of raw LDAP names (sAMAccountName, lastLogonTimestamp, dn)
- Resolves field-name alignment tech debt noted in SESSION_SNAPSHOT_2026-04-15
- 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"
