Vitruvyan
Docs
Knowledge_baseDevelopment

Vitruvyan Docs

Update Manager System 🚀

Last updated: Feb 20, 2026 14:30 UTC
Status: Phase 3 Complete — Package Manager implemented
CLI Command: vit update / vit upgrade (core) + vit install / vit remove (packages)
Architecture: Hybrid (Library + CLI, built-in to Core)

Overview

The Vitruvyan update system has two tiers:

TierCommandsScope
Corevit update, vit upgrade, vit rollbackSacred Orders, Graph, Conclave, Agents, Platform
Packagevit install, vit remove, vit list, vit search, vit infoNeural Engine, MCP, DSE, verticals

📦 See Package Manager System for full package management docs.

Objective 🎯

Define a distro-like update system for Vitruvyan Core:

  • notify when updates are available 🔔
  • provide one command to upgrade ⚙️
  • validate vertical compatibility before and after upgrade ✅
  • auto-rollback on failure 🛟

Expected outcome: zero Core forks across verticals and repeatable upgrades.

Architectural Decisions (Approved) ✅

Pattern: Industry-standard hybrid (apt/pip/dnf model)

  • Library: core.platform.update_manager.engine (business logic, testable)
  • CLI: vit command (user interface, built-in)
  • Distribution: Single package (pip install vitruvyan-core includes CLI)

Location: vitruvyan_core/core/platform/update_manager/

core/platform/update_manager/
├── engine/          # Library (compatibility, planning, execution)
│   ├── registry.py
│   ├── compatibility.py
│   ├── planner.py
│   └── executor.py
├── cli/             # CLI (commands, formatters)
│   ├── main.py
│   ├── commands/
│   └── formatters.py
└── tests/

CLI Commands (apt-style, concise):

  • vit update = check for updates (like apt update)
  • vit upgrade = apply upgrade (like apt upgrade)
  • vit plan = show upgrade plan
  • vit rollback = revert to previous version
  • vit channel = switch stable/beta

Versioning:

  • Git tags: v1.0.0 (stable), v1.1.0-beta.1 (beta)
  • SemVer strict (MAJOR.MINOR.PATCH)
  • Dual channels: stable (production), beta (early access)

End State 🧭

When a vertical team runs:

vitruvyan update check
vitruvyan update apply

the platform must:

  1. detect the latest Core release
  2. validate compatibility using vertical manifest + contracts version
  3. generate an upgrade plan (changes, risks, required tests)
  4. apply upgrade transactionally
  5. run vertical smoke tests
  6. confirm upgrade or automatically rollback

Non-Negotiable Principles 🧱

  • Verticals import only from contracts, never from Core internals.
  • No Core release ships without compatibility checks.
  • Every upgrade is traceable via audit logs and reports.
  • Contract breaking changes require major version + deprecation policy.

Logical Architecture 🏗️

Main components:

  • Release Registry (GitHub Releases API + metadata)
  • Compatibility Engine (version validation + manifest parsing)
  • Update Manager CLI (vit command)
  • Notification Engine (startup check + periodic polling)
  • Safety Layer (git snapshot, smoke tests, rollback)
  • Policy & Governance (contracts, versioning, deprecations)

Contract-Driven: All interactions governed by UPDATE_SYSTEM_CONTRACT_V1.md

1) Release Registry 📦

Source of truth for Core releases (start with GitHub Releases).

Minimum metadata per release:

  • Core version
  • supported contracts version
  • channel (stable, canary, lts)
  • machine-readable changelog
  • artifact checksum
  • migration notes

2) Compatibility Engine 🧠

Reads:

  • release metadata
  • vertical_manifest.yaml

Outputs:

  • compatible
  • compatible_with_warnings
  • blocked

Common block reasons:

  • Core version is outside supported range
  • contracts major mismatch
  • required capability no longer available

3) Update Manager CLI 🛠️

Command: vit (concise, apt-style)

Target commands:

  • vit update — check for updates (sync release registry)
  • vit upgrade — apply upgrade (with compatibility validation)
  • vit plan — show upgrade plan (changes, risks, tests)
  • vit rollback — revert to previous version
  • vit channel [stable|beta] — switch update channel
  • vit status — show current version + available updates

Minimum behavior:

  • human-readable output (tables, colors)
  • CI-friendly exit codes (0=success, 1=blocked, 2=error)
  • non-interactive mode (--yes) for automation
  • JSON output mode (--json) for programmatic usage

4) Notification Engine 🔔

Minimum channels:

  • notification on service startup
  • scheduled periodic check

Optional channels:

  • Slack/Webhook
  • internal dashboard

5) Safety Layer 🛡️

During update apply:

  • snapshot current state (commit/tag/deps/manifest)
  • apply update
  • execute minimal smoke suite
  • auto-rollback + report on failure

6) Policy & Governance 📜

  • Core SemVer
  • separate Contracts versioning
  • deprecation policy with support window
  • release channel policy (stable/canary/lts)

Implementation Tracklist 🧭

Phase 0 - Foundations (Week 1) 🧱

Goal: lock base rules and data schema.

Tasks:

  • Create contract: docs/contracts/platform/UPDATE_SYSTEM_CONTRACT_V1.md
    • Manifest schema (vertical compliance)
    • Smoke test interface (exit codes, timeout)
    • Versioning policy (SemVer, breaking changes)
    • Release metadata schema (JSON format)
  • Extend vertical_manifest.yaml with compatibility fields
  • Create directory structure: core/platform/update_manager/{engine,cli,tests}/
  • Define initial compatibility matrix (core version → contracts version)

Deliverables:

  • UPDATE_SYSTEM_CONTRACT_V1.md (binding contract)
  • Updated vertical_manifest.yaml template
  • Sample release metadata JSON
  • Skeleton code structure (empty modules with docstrings)

Definition of Done:

  • Contract approved by platform team
  • Manifest schema validated (pytest schema test)
  • One sample vertical using new schema (finance example)
  • Directory structure created + committed

Phase 1 - Compatibility Engine (Week 2) 🧠

Goal: block risky upgrades before apply.

Tasks:

  • Implement engine/registry.py (GitHub Releases API client)
  • Implement engine/compatibility.py (version range validation, SemVer parsing)
  • Implement engine/models.py (dataclasses: Release, CompatibilityResult)
  • Implement cli/commands/update.py (vit update command)
  • Generate compatibility report (text + JSON formats)

Deliverables:

  • Working vit update command
  • Compatibility report: compatible, compatible_with_warnings, blocked
  • JSON output mode: vit update --json
  • Unit tests: tests/test_compatibility.py (100% coverage)

Definition of Done:

  • vit update shows current version + latest available
  • Incompatible upgrades blocked with explicit reason
  • All unit tests pass (pytest)
  • Works with sample vertical (finance)

Phase 2 - Apply + Rollback (Weeks 3-4) 🔁

GoImplement engine/planner.py (upgrade plan generation)

  • Implement engine/executor.py (git checkout, pip install, snapshot)
  • Implement cli/commands/plan.py (vit plan command)
  • Implement cli/commands/upgrade.py (vit upgrade command)
  • Implement cli/commands/rollback.py (vit rollback command)
  • Pre-upgrade snapshot (git tag: pre-upgrade-<timestamp>)
  • Post-upgrade smoke tests (call vertical's smoke_tests/run.sh)
  • Automatic rollback on failure

Deliverables:

  • Working vit upgrade command (end-to-end flow)
  • Working vit rollback command
  • Upgrade audit log (.vitruvyan/upgrade_history.json)
  • Functional tests: tests/test_cli.py (E2E scenarios)

Definition of Done:

  • Compatible upgrade applies successfully + smoke tests pass

  • Failing smoke tests trigger automatic rollback

  • Rollback restores previous state (git + deps)

  • Audit log records all upgrade attempts

  • compatible update applies successfully

  • failing tests trigger automatic rollback

  • final state is consistent and verifiable

Phase 3 - CI/CD Gate (Week 5) 🚦

Goal: prevent Core releases that break active verticals.

Tasks:

  • multi-vertical compatibility CI pipeline
  • PR/release gating rules
  • compatibility report as CI artifact

Deliverables:

  • updated CI pipeline
  • release-blocking rule enabled

Definition of Done:

  • incompatible release is automatically blocked

Phase 4 - Notification System (Week 6) 📣

Goal: automatic update visibility for teams.

Tasks:

  • notifications in update check
  • scheduled update notifications
  • (optional) Slack webhook

Deliverables:

  • local notification + logs
  • configurable notification channel

Definition of Done:

  • vertical teams receive update alerts without manual polling

Phase 5 - Hardening & Governance (Weeks 7-8) 🧰

Goal: production-grade reliability.

Tasks:

  • full upgrade audit trail
  • support window policy (N supported versions)
  • rollback resilience tests
  • incident runbook for failed upgrades

Deliverables:

  • operational runbook
  • pre/post-upgrade checklist
  • vertical version status dashboard (minimal is fine)

Phase 0 (Foundations):

  • Create UPDATE_SYSTEM_CONTRACT_V1.md
  • Extend vertical_manifest.yaml (compatibility fields)
  • Define release_metadata.json schema
  • Create directory structure core/platform/update_manager/

Phase 1 (Compatibility Engine):

  • Implement engine/registry.py (GitHub API)
  • Implement engine/compatibility.py (version validation)
  • Implement vit update command
  • Generate JSON compatibility report
  • Unit tests (compatibility logic)

Phase 2 (Apply + Rollback):

  • Implement engine/planner.py (upgrade plan)
  • Implement engine/executor.py (apply/rollback)
  • Implement vit upgrade command
  • Implement vit rollback command
  • Create vertical smoke test template
  • Add upgrade audit logging

Phase 3 (CI/CD Gate):

  • Implement CI compatibility gate
  • Multi-vertical test matrix
  • Release blocking rules

Phase 4 (Notifications):

  • Startup update check
  • Periodic polling (configurable)
  • Webhook notifications (optional)

Phase 5 (Hardening):

  • Operational runbook
  • Rollback resilience tests
  • Version status dashboard
  • implement update apply
  • implement update rollback
  • create vertical smoke test pack Developer workflow (vertical team):
# 1. Check for updates
vit update
# Output: "New version v1.2.0 available (current: v1.1.0)"
#         "Compatibility: ✅ COMPATIBLE"
 
# 2. Review upgrade plan
vit plan --target v1.2.0
# Output: changelog, affected contracts, required tests
 
# 3. Apply upgrade
vit upgrade
# Platform auto-executes:
#   - Create snapshot (git tag pre-upgrade-20260219-164500)
#   - Checkout v1.2.0
#   - Install dependencies
#   - Run smoke tests
#   - Confirm OR rollback
 
# 4. Verify
vit status
# Output: "Core v1.2.0 (upgraded from v1.1.0 on 2026-02-19)"

Rollback flow (if issues found post-upgrade):

vit rollback
# Restores: git state + dependencies + audit log entry
domain_name: "example"
domain_version: "0.1.0"
status: "active"
 
compatibility:
  min_core_version: "1.2.0"
  max_core_version: "1.4.x"
  contracts_major: 1
  update_channel: "stable" # stable|canary|lts
 
ownership:
  team: "domain-team"
  tech_lead: "name.surname"
  contact: "team@example.com"

Standard Operating Flow (SOP) 🔄

  1. vertical team runs vitruvyan update check
  2. if compatible, run vitruvyan update plan
  3. approve and run vitruvyan update apply
  4. platform executes smoke tests
  5. if pass, upgrade is confirmed
  6. if fail, rollback runs and ticket/report is generated

Main Risks & Mitigations ⚠️

MVP Path (3 weeks, immediate value):

  1. Phase 0 (Week 1): Foundations + contract
  2. Phase 1 (Week 1-2): vit update working (read-only checks)
  3. Phase 2 (Week 2-3): vit upgrade + vit rollback (manual testing)

Production Hardening (additional 2-4 weeks): 4. Phase 3 (Week 4): CI gates (prevent breaking releases) 5. Phase 4 (Week 5): Notifications (proactive alerts) 6. Phase 5 (Week 6-7): Governance + runbooks

This sequence minimizes architectural risk before vertical expansion.

Quick-win milestone: After Week 2, vertical teams can run vit update to check compatibility (immediate safety net, even without auto-apply)

  • Risk: unreliable rollback. Mitigation: atomic snapshot + recurring rollback drills.

Suggested Ownership 👥

  • Platform/Core team: release registry, contracts, update manager
  • Vertical teams: manifest, smoke tests, vertical compliance
  • DevOps/SRE: CI gates, notifications, observability, runbooks

KPIs to Monitor 📈

  • successful upgrades (%)
  • mean time to upgrade (MTTU)
  • rollback rate (%)
  • incompatibilities caught pre-deploy
  • post-upgrade incident count
  1. Phase 0 and Phase 1 first (breakage prevention)
  2. Phase 2 next (apply + rollback)
  3. Phase 3 before scaling vertical count
  4. Phase 4 and 5 for continuous operations

This sequence minimizes architectural risk before vertical expansion.

Implementation Progress 📊

Last updated: Feb 19, 2026 18:30 UTC
Current Phase: Phase 1 (Compatibility Engine)
Branch: feature/update-manager-vit-cli

✅ Phase 0 Complete (Feb 19, 2026)

Foundations + Contract

  • Directory structure created: vitruvyan_core/core/platform/update_manager/{engine,cli,tests}/
  • Contract published: docs/contracts/platform/UPDATE_SYSTEM_CONTRACT_V1.md (15 sections, binding)
    • P0 amendments applied (wildcard semantics, path resolution, checksum, dirty tree, audit trail)
  • Manifest template extended: docs/contracts/verticals/templates/vertical_manifest.yaml
  • Finance vertical example: examples/verticals/finance/vertical_manifest.yaml + smoke tests
  • Skeleton code: 13 Python modules with docstrings + NotImplementedError stubs
  • Git commit: 089178e (40 files, +4655/-257 lines)
  • Contract v1.0.1: 3afc2db (P0 compliant)

Key Decisions:

  • CLI command: vit (apt-style, concise)
  • Architecture: Hybrid (Library + CLI, built-in to Core)
  • Location: vitruvyan_core/core/platform/update_manager/
  • Versioning: Git tags strict SemVer (v1.0.0, v1.1.0-beta.1)
  • Channels: stable (production), beta (early access)

✅ Phase 1 Complete (Feb 19, 2026)

Compatibility Engine — Read-Only Check

Implemented modules:

  1. engine/registry.py (GitHub Releases API client)

    • ReleaseRegistry.fetch_latest(channel) → fetch latest release from GitHub
    • ReleaseRegistry.fetch_all(channel) → fetch all releases (filtered by channel)
    • ReleaseRegistry.verify_checksum(release) → verify Git commit SHA
    • ReleaseRegistry._parse_semver(version) → parse SemVer for sorting
    • Uses stdlib urllib (zero external dependencies)
    • Pagination support (100 releases per request)
    • Downloads releases.json asset from GitHub Release
    • Filters by channel (stable, beta)
    • Sorts by SemVer (descending)

  2. engine/compatibility.py (Version matching + validation)

    • CompatibilityChecker.check(current, target, manifest) → validate compatibility
    • CompatibilityChecker._match_version(version, pattern, operator) → SemVer comparison (>=, <=, ==)
    • CompatibilityChecker._match_wildcard(version, pattern) → wildcard matching (1.x.x permissive)
    • CompatibilityChecker.parse_semver(version) → parse SemVer tuple
    • CompatibilityChecker.check_contracts_major() → contracts version validation
    • Blocks incompatible upgrades (target < min or target > max)
    • Returns CompatibilityResult (compatible bool + blocking_reason)

  3. cli/commands/update.py (vit update command)

    • cmd_update(args) → main command logic
    • get_current_version() → detect current Core version (3 strategies: __version__, git describe, fallback)
    • find_vertical_manifest() → walk up directory tree to find vertical_manifest.yaml
    • Displays: current version, latest version, release date, changes (breaking/features/fixes)
    • Compatibility check with vertical manifest (if found)
    • Shows migration guide URL
    • Next steps: vit upgrade --channel stable
    • Format: Human-readable console output (emojis, colors)

  4. cli/main.py (CLI entry point)

    • Imports register_update_command from commands/update.py
    • Registers vit update subcommand with argparse
    • Executes args.func(args) pattern (command dispatch)
    • Logging configured (INFO level)
    • Stub commands for Phase 2+ (upgrade, plan, rollback, channel, status)

  5. cli/formatters.py (Output formatters)

    • format_release_info(release) → format Release object for display
    • format_compatibility_result(result) → format CompatibilityResult
    • OutputFormatter.color(text, color) → ANSI colored output

  6. pyproject.toml (Package configuration)

    • Project metadata: name, version, description, authors, license
    • Dependencies: pyyaml, pydantic, httpx, psycopg2, redis, qdrant-client, openai, langgraph
    • Optional dependencies: dev (pytest, black, ruff, mypy), mcp (anthropic), monitoring (prometheus-client)
    • CLI entry point: vit = "vitruvyan_core.core.platform.update_manager.cli.main:cli_main"
    • Setuptools configuration: packages.find, pytest.ini_options
    • Tool configuration: black, ruff, mypy

Implementation Details:

  • Zero breaking changes: All code isolated in core/platform/update_manager/
  • Stdlib-first: Uses urllib (no requests dependency yet)
  • Error handling: NetworkError for GitHub API failures
  • Timeout protection: 10-second timeout for network requests
  • Graceful degradation: Falls back to "unknown" version if detection fails
  • Vertical discovery: Walks up from CWD to Git repo root looking for vertical_manifest.yaml

Testing Strategy (next):

  • Unit tests: tests/test_registry.py (mock GitHub API responses)
  • Unit tests: tests/test_compatibility.py (wildcard matching, SemVer comparison)
  • Integration test: tests/test_vit_update_e2e.py (actual GitHub API call)
  • Manual test: pip install -e . && vit update --channel stable

Known Limitations (Phase 1):

  • Current version detection: hardcoded fallback to "unknown" if __version__ and git describe fail
  • Contracts version: hardcoded to "1.0.0" (should read from Core metadata in Phase 2)
  • No caching: GitHub API called on every vit update (add cache in Phase 2)
  • No rate limit handling: Will fail after 60 requests/hour (unauthenticated)
  • Manifest discovery: stops at Git repo root (could support custom paths)

🔜 Phase 2 Next (Week 3)

Update Executor — Apply Upgrade

Modules to implement:

  1. engine/planner.py (UpgradePlanner)

    • Generate upgrade plan (changes, risks, tests)
    • Estimate upgrade duration
    • Check for breaking changes
    • Validate prerequisites (clean working tree, sufficient disk space)

  2. engine/executor.py (UpgradeExecutor)

    • Execute upgrade transaction (git checkout, pip install)
    • Create snapshot tag before upgrade
    • Run vertical smoke tests
    • Rollback on failure (restore snapshot)
    • Write audit log entry

  3. cli/commands/upgrade.py (vit upgrade command)

    • Interactive confirmation (show plan, ask consent)
    • Non-interactive mode (--yes flag)
    • Target version selection (--target v1.2.0)
    • Progress indicators (spinner, percentage)
    • Error reporting (detailed diagnostics)

  4. cli/commands/plan.py (vit plan command)

    • Show upgrade plan without applying
    • Risk assessment (breaking changes, migration complexity)
    • Smoke test preview (timeout, exit codes)

  5. cli/commands/rollback.py (vit rollback command)

    • Revert to previous version (snapshot tag)
    • Restore dependencies (requirements.txt snapshot)
    • Update audit log

Timeline: Week 3 (Feb 20-26, 2026)

Definition of Done:

  • vit upgrade working end-to-end (manual testing)
  • vit rollback restores previous version
  • Smoke tests run automatically after upgrade
  • Audit log created (.vitruvyan/upgrade_history.json)
  • Integration tests pass (mocked GitHub API)

🔜 Phase 3-5 (Weeks 4-7)

CI Gates, Notifications, Governance (see Masterplan sections above)

✅ Phase 2 Complete (Feb 19, 2026)

Update Executor — Apply Upgrade with Rollback

Implemented modules:

  1. engine/planner.py (UpgradePlanner)

    • plan(from, to, release, manifest_path) → generates UpgradePlan
    • validate_prerequisites() → blocks on dirty working tree (P0 contract)
    • _check_clean_working_tree() → git diff-index --quiet HEAD --
    • _check_disk_space() → requires 100MB minimum
    • _determine_tests(manifest_path) → discovers vertical smoke tests
    • _estimate_downtime(breaking, tests) → base 30s + tests 60s/test + 20% buffer
    • PrerequisiteError: raised when dirty tree or insufficient disk space

  2. engine/executor.py (UpgradeExecutor)

    • apply(plan, manifest_path) → executes full upgrade transaction
    • rollback() → reverts to snapshot tag
    • create_snapshot() → creates Git tag pre-upgrade-YYYYMMDD-HHMMSS
    • run_smoke_tests(manifest_path) → executes <vertical_root>/smoke_tests/run.sh
    • _write_audit_log() → writes to .vitruvyan/upgrade_history.json (P0 contract)
    • _checkout_version(version) → git checkout v{version}
    • _get_audit_log_path() → resolves to Git repo root (P0 contract)
    • Auto-rollback: triggers on smoke test failure or any exception

  3. cli/commands/upgrade.py (vit upgrade command)

    • Interactive workflow:
      1. Fetch target release from GitHub (latest or --target)
      2. Compatibility check with vertical manifest
      3. Generate upgrade plan (planner)
      4. Display plan: changes (breaking/features/fixes), downtime estimate, smoke tests
      5. Confirmation prompt (skip with --yes)
      6. Execute upgrade (executor)
      7. Show snapshot tag for rollback
    • Flags: --channel stable|beta, --target VERSION, --yes
    • Exit codes: 0 = success, 1 = error/rollback

  4. cli/commands/plan.py (vit plan command)

    • Display upgrade plan without applying
    • Sections:
      • Timeline: estimated downtime + rollback strategy
      • Changes: breaking/features/fixes (limit 5 each for readability)
      • Smoke tests: list all discovered tests
      • Risk assessment: HIGH/MEDIUM/LOW (based on breaking changes + tests)
    • Next steps: suggests vit upgrade command
    • Required arg: --target VERSION

  5. cli/commands/rollback.py (vit rollback command)

    • Reverts to last upgrade snapshot
    • Reads snapshot tag from .vitruvyan/upgrade_history.json
    • Confirmation prompt
    • Executes git checkout {snapshot_tag}
    • Verifies with git describe --tags

  6. cli/main.py (CLI orchestration)

    • Registered upgrade, plan, rollback commands
    • Updated imports and help text
    • Phase 2 complete marker

Implementation Details:

  • P0 contract compliance:
    • Dirty tree blocking: zero tolerance (no --force override)
    • Audit log location: Git repo root .vitruvyan/upgrade_history.json
    • Snapshot tags: pre-upgrade-YYYYMMDD-HHMMSS format
  • Smoke tests:
    • Location: <vertical_root>/smoke_tests/run.sh (P0 contract)
    • Timeout: from manifest smoke_tests_timeout (default 180s)
    • Exit codes: 0 = pass, 1 = fail, 2 = error
    • Auto-rollback on failure
  • Audit log format: 
    {
  "upgrades": [
    {
      "timestamp": "2026-02-19T18:30:00",
      "from_version": "1.0.0",
      "to_version": "1.2.0",
      "snapshot_tag": "pre-upgrade-20260219-183000",
      "success": true
    }
  ]
}

-Graceful degradation:

  • Disk space check: non-blocking (warning only)
  • No smoke tests: non-blocking (warning: "risky upgrade")
  • Latest version unknown: show warning, allow proceed

Known Limitations (Phase 2):

  • pip install skipped: Requires Python venv management (Phase 3)
  • requirements.txt snapshot: Not implemented (Phase 3)
  • No channel command: Switching channels not yet implemented
  • No status command: Current version + updates summary not yet implemented
  • Git-only: Assumes Git repository (no tarball support yet)

Testing Performed:

  • ✅ Manual test: vit upgrade --help (arg parsing)
  • ✅ Manual test: vit plan --help (arg parsing)
  • ✅ Manual test: vit rollback --help (arg parsing)
  • ✅ Prerequisite validation: dirty tree detection
  • ✅ Snapshot creation: pre-upgrade-* tag format
  • ✅ Audit log: JSON write/read
  • ⚠️ End-to-end upgrade: requires GitHub release (Phase 3)

File Changes (commit cfb2169):

  • 6 files changed, +1049/-47 lines
  • New files: upgrade.py, plan.py, rollback.py
  • Modified: planner.py, executor.py, main.py

✅ Phase 3 Complete (Feb 19, 2026)

CI/CD Gates — Prevent Breaking Releases

Implemented modules:

  1. ci/contract_validator.py (ContractValidator)

    • validate_manifest(manifest_path) → ValidationResult
    • validate_multiple(paths) → List[ValidationResult]
    • Validation rules (UPDATE_SYSTEM_CONTRACT_V1 compliance):
      • Required fields: domain_name, domain_version, status, compatibility, ownership
      • Compatibility section: min/max_core_version, contracts_major, update_channel
      • Ownership section: team, tech_lead, contact (email format)
      • Version constraints: SemVer or wildcard (e.g., 1.x.x)
      • Contracts major: must match Core version
      • Update channel: "stable" or "beta"
      • Smoke test timeout: 60-600 seconds (if provided)
    • discover_verticals(root_dir) → finds all vertical_manifest.yaml files
    • Validation checks:
      • Schema compliance (required fields, types)
      • min_core_version ≤ max_core_version
      • Smoke test existence (warning if missing)
      • Smoke test executability (warning if not executable)

  2. ci/pytest_integration.py (pytest markers & fixtures)

    • Decorator: @compatibility_test (marks tests for CI filtering)
    • Fixtures:
      • repo_root: Searches for Git root (.git/)
      • vertical_manifests: Discovers all manifests (session scope)
      • active_verticals: Filters status="active" manifests
      • contract_validator: Initialized ContractValidator
      • compatibility_check_helper: Assertion helper (raises on invalid)
    • Parametrization: parametrize_verticals(metafunc) → runs tests once per vertical
    • Markers registration: compatibility, slow

  3. ci/release_blocker.py (ReleaseBlocker)

    • check_release(target_version) → BlockingReport
    • check_manifest_compliance() → BlockingReport
    • Blocking reasons:
      • INVALID_MANIFEST: schema violation
      • INCOMPATIBLE_VERTICAL: version range mismatch
      • CONTRACT_VIOLATION: compliance test failed
      • NO_VERTICALS: no manifests found (suspicious)
    • BlockingReport:
      • blocked: bool (True = block release)
      • reason: BlockingReason (enum)
      • details: str (error messages)
      • failing_verticals: List[str] (paths to failing manifests)
      • total_verticals: int
      • exit_code() → 0 (pass) | 1 (block)
      • to_json() → JSON artifact for CI
    • CLI entry point: python -m vitruvyan_core.core.platform.update_manager.ci.release_blocker

  4. .github/workflows/update_manager_ci.yml (GitHub Actions)

    • Triggers:
      • Pull requests (branches: main, develop)
      • Release tags (v*)
      • Manual dispatch (target_version input)
    • Jobs:
      1. validate-manifests: Contract compliance check
        • Runs: release_blocker --check-compliance
        • Uploads: compliance_report.json artifact
        • Blocks: if any manifest invalid
      2. check-compatibility: Version range validation (tags only)
        • Extracts version from tag (v1.2.0 → 1.2.0)
        • Runs: release_blocker <version>
        • Uploads: compatibility_report.json artifact
        • Comments on PR if blocked (reason, failing verticals)
        • Blocks: if any vertical incompatible
      3. run-compatibility-tests: Pytest suite
        • Runs: pytest -m compatibility
        • Uploads: compatibility-tests.xml (JUnit format)
        • Blocks: if any test fails
      4. summary: Aggregates all job results
        • Fails if any job failed
    • Paths filter: Triggers only if Core or manifests changed

  5. tests/test_compatibility.py (8 compatibility tests)

    • test_all_manifests_valid: All manifests comply with contract ✅
    • test_active_verticals_have_required_fields: Active verticals valid ✅
    • test_version_constraints_valid: SemVer or wildcard format ✅
    • test_contracts_major_matches_core: Contracts version alignment ✅
    • test_smoke_tests_exist: Smoke tests present (warning if missing) ✅
    • test_update_channel_valid: Channel is "stable" or "beta" ✅
    • test_smoke_test_timeout_in_range: Timeout 60-600 seconds ✅
    • test_manifest_discovery_works: At least 1 manifest found ✅
    • test_vertical_manifest_individual: Parametrized test (1 per vertical)

  6. tests/conftest.py (pytest configuration)

    • Imports fixtures from ci/pytest_integration.py
    • Registers markers: compatibility, slow
    • Configures test parametrization

  7. pytest.ini (global marker registration)

    • Added: compatibility: Update Manager compatibility tests (CI gates)

Implementation Details:

  • Wildcard matching: 1.x.x matches any 1.*.* (permissive, industry standard)
  • SemVer validation: Regex ^\d+\.\d+\.\d+(-[\w.]+)?$ (supports pre-release)
  • Version comparison: Basic major.minor.patch ordering (wildcards → 999)
  • Smoke test location: <vertical_root>/smoke_tests/run.sh (P0 contract)
  • Manifest discovery paths:
    • examples/verticals/*/vertical_manifest.yaml
    • domains/*/vertical_manifest.yaml
  • CI artifacts retention: 30 days (tests), 90 days (compatibility reports)

Testing Performed:

  • ✅ Manual: python -m ...release_blocker --check-compliance
    • Result: 1 vertical compliant (finance), exit 0
  • ✅ Manual: python -m ...release_blocker 1.2.0
    • Result: Compatible (1.2.0 within 1.x.x), exit 0
  • ✅ Manual: python -m ...release_blocker 2.0.0
    • Result: Blocked (2.0.0 > 1.x.x), exit 1
  • ✅ Pytest: pytest -m compatibility
    • Result: 8/8 tests passed
  • ✅ ContractValidator: Finance vertical passes all checks
  • ✅ Wildcard matching: 1.x.x correctly matches 1.2.0, rejects 2.0.0
  • ✅ Fixtures: vertical_manifests, contract_validator work correctly

Known Limitations (Phase 3):

  • No GitHub release test: Workflow not triggered yet (requires actual release tag)
  • Single vertical: Only finance vertical exists (need more for matrix testing)
  • No pre-release handling: Workflow doesn't distinguish stable/beta channels
  • Comment posting: Requires GitHub token with PR write permissions

File Changes (commit c00d064):

  • 8 files changed, +1187 lines
  • New files (7):
    • .github/workflows/update_manager_ci.yml (172 lines)
    • ci/__init__.py (20 lines)
    • ci/contract_validator.py (325 lines)
    • ci/pytest_integration.py (150 lines)
    • ci/release_blocker.py (250 lines)
    • tests/conftest.py (33 lines)
    • tests/test_compatibility.py (175 lines)
  • Modified (1):
    • pytest.ini (+1 marker)

Previous

Next

On this page

Update Manager System 🚀OverviewObjective 🎯Architectural Decisions (Approved) ✅End State 🧭Non-Negotiable Principles 🧱Logical Architecture 🏗️1) Release Registry 📦2) Compatibility Engine 🧠3) Update Manager CLI 🛠️4) Notification Engine 🔔5) Safety Layer 🛡️6) Policy & Governance 📜Implementation Tracklist 🧭Phase 0 - Foundations (Week 1) 🧱Phase 1 - Compatibility Engine (Week 2) 🧠Phase 2 - Apply + Rollback (Weeks 3-4) 🔁Phase 3 - CI/CD Gate (Week 5) 🚦Phase 4 - Notification System (Week 6) 📣Phase 5 - Hardening & Governance (Weeks 7-8) 🧰Standard Operating Flow (SOP) 🔄Main Risks & Mitigations ⚠️Suggested Ownership 👥KPIs to Monitor 📈Recommended Rollout Order 🗺️Implementation Progress 📊✅ Phase 0 Complete (Feb 19, 2026)✅ Phase 1 Complete (Feb 19, 2026)🔜 Phase 2 Next (Week 3)🔜 Phase 3-5 (Weeks 4-7)✅ Phase 2 Complete (Feb 19, 2026)✅ Phase 3 Complete (Feb 19, 2026)