feat(ui): establish shared MailStack application shell

Author: victorsteele

.github/pull_request_template.md

@@ -19,6 +19,7 @@ Describe the change and the operational problem it solves.
 - [ ] `python scripts/test_documents.py`
 - [ ] `python scripts/manage_designs.py --root . check`
 - [ ] `python scripts/test_designs.py`
+- [ ] `python scripts/test_ui_foundation.py`
 - [ ] `python scripts/check_documentation_policy.py --base HEAD^ --head HEAD`
 
 ## Verification

.github/workflows/ci.yml

@@ -59,6 +59,9 @@ jobs:
       - name: UI design system tests
         run: python scripts/test_designs.py
 
+      - name: Shared UI foundation contract tests
+        run: python scripts/test_ui_foundation.py
+
       - name: Feature documentation policy
         env:
           DOCUMENTATION_BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
@@ -98,6 +101,12 @@ jobs:
         working-directory: public-site/contact_service
         run: python test_contact_app.py
 
+      - name: Contact service Ruff
+        run: python -m ruff check --config mailbox-app/pyproject.toml public-site/contact_service/contact_app.py
+
+      - name: Contact service Bandit
+        run: python -m bandit -c mailbox-app/.bandit -q public-site/contact_service/contact_app.py
+
       - name: Django checks
         working-directory: mailbox-app
         run: |

CHANGELOG.md

@@ -6,10 +6,13 @@ All notable repository-level changes are recorded here. Application history befo
 
 ### Changed
 
+- Implemented PHASE-002 shared UI foundation and application shell with frozen design tokens, responsive authenticated navigation, an isolated sign-in shell, local SVG brand/icon assets, accessible focus handling, and preserved page business logic.
+- Added dependency-free UI foundation contract tests, Django shell functional tests, CI enforcement, forensic-audit integration, and synchronized user/design documentation.
+- Hardened cross-platform verification by deterministically closing contact-service SQLite connections, limiting POSIX permission assertions to POSIX runtimes, extending Ruff/Bandit coverage to the standalone contact service, and canonicalizing source-release ZIP host metadata and storage so Windows and Linux produce byte-identical archives.
 - Imported and verified the complete 25-image MailStack UI and logo reference archive as `MAILSTACK-UI-DESIGN-INTAKE-001`.
 - Frozen `MAILSTACK-UI-FOUNDATION-001` with screen classification, component, responsive, accessibility, future-roadmap, and implementation-status specifications.
 - Added immutable design-asset hashing, PNG integrity validation, deterministic manifest synchronization, contract tests, CI gates, and forensic-audit integration.
-- Optimized deterministic source packaging by storing already-compressed media without redundant DEFLATE work.
+- Made deterministic source packaging independent of host ZIP metadata and zlib implementation by using canonical POSIX metadata, fixed timestamps, empty optional metadata, and stored entries for every release member.
 - Adopted **MailStack** as the public open-source project name.
 - Set `https://github.com/vibtools/MailStack` as the canonical repository.
 - Rebuilt the root README with SEO-oriented positioning for a self-hosted mail server and shared team inbox.

CONTRIBUTING.md

@@ -26,6 +26,9 @@ From the repository root:
 python scripts/manage_documents.py check
 python scripts/test_documents.py
 python scripts/check_documentation_policy.py --base HEAD^ --head HEAD
+python scripts/manage_designs.py --root . check
+python scripts/test_designs.py
+python scripts/test_ui_foundation.py
 python scripts/check_docs.py
 python scripts/validate_templates.py
 python scripts/test_installer.py
@@ -52,13 +55,13 @@ The full gate runs tests, coverage, Ruff, Bandit, Django checks, contact-service
 UI work must begin from the frozen design intake and shared foundation. Preserve original PNGs,
 update `design/DESIGN_MANIFEST.json` only through the maintained workflow, implement one page per
 reviewed patch, and do not activate planned controls without an approved backend/security phase.
-Run `python scripts/manage_designs.py --root . check` and `python scripts/test_designs.py`.
+Run `python scripts/manage_designs.py --root . check`, `python scripts/test_designs.py`, and `python scripts/test_ui_foundation.py`.
 
 Start a maintained phase before implementation:
 
 ```bash
 python scripts/manage_documents.py new-phase \
-  --phase-id PHASE-002 \
+  --phase-id PHASE-003 \
   --title "Feature title" \
   --summary "What the phase changes for users"
 ```

README.md

@@ -202,6 +202,7 @@ Run the complete repository gate from the project root:
 ```bash
 python scripts/manage_designs.py --root . check
 python scripts/test_designs.py
+python scripts/test_ui_foundation.py
 python scripts/forensic_audit.py --root . --full
 ```
 

ROADMAP.md

@@ -21,7 +21,8 @@ This roadmap is directional. Security, data integrity and backward compatibility
 ## UI design baseline
 
 - Preserve `MAILSTACK-UI-DESIGN-INTAKE-001` and `MAILSTACK-UI-FOUNDATION-001` as the approved visual reference baseline
-- Implement one existing page per reviewed patch after shared foundation work
+- Complete PHASE-002 shared runtime tokens, responsive application shell, local assets, and accessibility contracts
+- Implement one existing page per reviewed patch on top of the qualified shared foundation
 - Keep planned and future-review screens inactive until architecture and security phases approve them
 - Require responsive, accessibility, security, regression, documentation and CI evidence for each page
 

docs/FOLDER_STRUCTURE.md

@@ -15,11 +15,14 @@ mailbox-app/                Django team mailbox application
   deployment/               Legacy-compatible deployment assets
   requirements/             Pinned runtime and development dependencies
   scripts/                  Backup, restore, deploy, health and verification tools
-  static/                   Application CSS and JavaScript
+  static/                   Application CSS, JavaScript, local brand assets and SVG icon sprite
+    brand/                  Runtime copy of the canonical MailStack logo
+    css/                    Existing page CSS and the frozen shared foundation layer
+    icons/                  Self-hosted shared SVG symbol sprite
   templates/                Django HTML templates
   tests/                    Unit, integration, functional, reliability and security tests
 public-site/                Static site and isolated contact WSGI service
-scripts/                    Repository audit, documentation, rendering, testing and release tools
+scripts/                    Repository audit, documentation, UI contracts, rendering, testing and release tools
 install.sh                  Clean Ubuntu 24.04 installer
 VERSION                     Canonical release version
 ```

docs/FORENSIC_AUDIT_REPORT.md

@@ -1,6 +1,6 @@
 # Forensic audit report — MailStack 1.3.0 RC1
 
-**Baseline audit date:** 2026-07-24
+**Baseline audit date:** 2026-07-25
 **Release version:** `1.3.0-rc.1`
 **Target runtime:** Ubuntu Server 24.04 LTS and CPython 3.12
 **Release classification:** CI-qualified and clean-clone-qualified open-source release candidate
@@ -12,13 +12,15 @@
 | Baseline feature preservation | PASS |
 | Repository structure and public documentation | PASS |
 | User manual, how-to, admin guide and phase-document baseline | PASS |
-| UI design intake, immutable-source manifest and design contract tests | PASS locally; CI pending for this phase |
+| UI design intake, immutable-source manifest and design contract tests | PASS in GitHub Actions run `30165905840` |
+| PHASE-002 shared UI foundation structural contracts | PASS locally — 8 tests |
+| PHASE-002 local Django, coverage and mailbox lint qualification | PASS — 195 passed, 1 skipped, 94.99% coverage |
 | Deterministic documentation index, manifest and change policy | PASS |
 | Complete AGPL-3.0 license text | PASS |
 | Source secret/private-data safety gate | PASS |
 | Python, JSON, YAML and shell syntax | PASS |
 | Django application tests and coverage | PASS |
-| Ruff and Bandit | PASS |
+| Ruff and Bandit | PASS for mailbox application; standalone contact-service gates added to final verifier and CI |
 | Django checks and migration drift | PASS |
 | Public contact-service tests | PASS |
 | Installer and operations contract tests | PASS |
@@ -92,16 +94,18 @@ See `FEATURE_MATRIX.md` for the feature-by-feature verification record.
 13. A root `documents/` baseline now provides maintained user, administrator and phase documentation.
 14. Deterministic synchronization, draft blocking and diff-based CI policy prevent maintained feature changes from merging without substantive documentation.
 15. The complete 25-image UI and logo archive is preserved with stable IDs, SHA-256 hashes, PNG structural validation, scope classification, and CI enforcement.
+16. PHASE-002 adds the frozen runtime design tokens, responsive authenticated and sign-in shells, local SVG assets, accessible navigation behavior, and focused UI contract gates without changing page business logic.
+17. Cross-platform verification now closes contact-service SQLite handles deterministically, preserves POSIX-only permission assertions, and subjects the standalone contact service to Ruff and Bandit in both the full forensic gate and CI.
 
 ## Automated evidence
 
-- Django tests: **189 passed, 0 failed**
+- Django tests: **195 passed, 1 capability-based skip, 0 failed**
 - Application coverage: **94.99%**; minimum: **85%**
 - Ruff: **PASS**
 - Bandit: **PASS**
 - Django system check: **PASS**
 - Migration drift: **none**
-- Contact-service test program: **PASS**
+- Contact-service test program: **PASS**, including deterministic connection-close regression coverage
 - Deployment templates rendered: **13**, unresolved tokens: **0**
 - Installer plans: **2 valid and 9 invalid cases**, all passed
 - Backup/restore/health contracts: **PASS**
@@ -127,6 +131,16 @@ Web requests and Maildir ingestion remain separate services. Gunicorn worker/thr
 
 The repository includes an SEO-oriented README, logo asset, release/download/license/platform/language/community badges, GitHub topics and description guidance, full license, notice, security policy, contribution guide, code of conduct, support policy, roadmap, issue/PR templates, CODEOWNERS, Dependabot, CI, release workflow, installation/build/development/operations/security documentation and Vib Tools ecosystem links.
 
+
+## PHASE-002 audit boundary
+
+The phase changes only the shared base template, shared static foundation assets and JavaScript,
+focused tests, the contact-service connection-lifecycle helper, CI/audit tooling, generated
+inventories, and required documentation. It contains no model, migration, URL, form, permission,
+mail-flow, ingestion schema, deployment-template, or package change. Local dependency-backed tests
+and coverage passed; the final overwrite verifier must pass before commit, and GitHub Actions must
+pass before remote qualification.
+
 ## External acceptance gates
 
 Before stable promotion: