Release: Engineering Operating System v5.0
Tag: v5.0-ai-development-environment (provisional — commit recorded at Git freeze)
Commit: (recorded after Phase 10-9 Git freeze)
Previous baseline: v4.2-public-experience-platform
Baseline date: 2026-06-27
Runtime platform freeze: unchanged — v4.2-public-experience-platform / Public Experience Platform
Finance freeze: unchanged — finance-v1.0 / docs/FINANCE-V1-FROZEN.md
All prior platform freezes: preserved through v4.2-public-experience-platform
Release summary
Engineering Operating System (EOS) v1.0 is the freeze-ready baseline for Phase 10 — AI Development Environment — following the additive documentation pattern established by prior platform freeze releases.
Phase 10 delivers the permanent engineering design authority for ZAIXOS. EOS governs how platforms and products are discovered, specified, implemented, reviewed, hardened, frozen, and released using AI-assisted tooling. EOS is not runtime architecture — it does not define module boundaries, platform contracts, or application behavior.
Phase 10 delivery:
- 10-1 Discovery —
phase-10-ai-development-environment-discovery.md - 10-2 Specification —
runtime/specification/archive/phase-10-ai-development-environment-specification.md - 10-3 Foundation —
.cursor/workspace, manifests, prompts, templates, knowledge hierarchy,ENGINEERING_INDEX.md - 10-4 Content Review — comprehensive EOS content audit
- 10-5 Refinement — report format harmonization, authority chain, metadata, agent/MCP documentation
- 10-6 Validation — full EOS validation (documentation-only)
- 10-7 Hardening —
GovernanceDocumentationTestextension,EngineeringOperatingSystemIntegrityTest,EosIntegritySupport - 10-8 Freeze Preparation — this release document (Git freeze: Phase 10-9 — Developer only)
Tag name: v5.0-ai-development-environment
Git freeze (10-9): Pending — Developer executes GIT_FREEZE_PROCEDURE.md after Architecture Review approval.
Next phase: Clinic AI Platform (runtime) — not started; must follow EOS methodology.
Engineering philosophy
EOS encodes twelve immutable engineering principles from the Phase 10 specification:
| # | Principle |
|---|---|
| 1 | Architecture First |
| 2 | Documentation First |
| 3 | Human Approval |
| 4 | Deterministic Engineering |
| 5 | Frozen Platform Protection |
| 6 | Review Before Freeze |
| 7 | Review Before Implementation |
| 8 | Additive Evolution |
| 9 | Repository Is Truth |
| 10 | AI Assists — Never Approves |
| 11 | Minimize Scope |
| 12 | Specifications Override Implementation |
Authority chain (conflict resolution):
docs/releases/
> docs/architecture/
> docs/development/ (EOS)
> docs/company/ + docs/product/
> knowledge/
> Chat historyRoot methodology: AI_DEVELOPMENT_ENVIRONMENT.md
Asset index: ENGINEERING_INDEX.md
Design authority: runtime/specification/archive/phase-10-ai-development-environment-specification.md
EOS components
| Component | Location | Count |
|---|---|---|
Cursor rules (.mdc) | .cursor/rules/ | 9 |
| Rules catalog | .cursor/rules/catalog/ | 11 |
| Skills | .cursor/skills/*/SKILL.md | 10 |
| Subagents | runtime/manifests/defaults/delegation-manifest.md + .cursor/agents/ stubs | 10 |
| Commands | templates/prompts/commands/ | 10 |
| Phase prompts | templates/prompts/phases/ | 8 |
| Templates | templates/ | 7 |
| Knowledge hierarchy | knowledge/ | 7 subdirectories + index |
| MCP governance | .cursor/mcp/ (canonical) | Not enabled |
Rules
| Category | ID | Rule file | alwaysApply |
|---|---|---|---|
| EOS authority | — | 00-eos-authority.mdc | true |
| Freeze & Boundary | A | 10-freeze-boundary.mdc | true |
| Architecture Patterns | B | 20-architecture-patterns.mdc | true |
| Implementation Discipline | C | 30-implementation.mdc | false |
| Phase Scope | D | 40-phase-scope.mdc | false |
| Documentation | E | 50-documentation.mdc | false |
| AI Alignment | F | 60-ai-alignment.mdc | false |
| Tooling & Safety | G | 70-tooling-safety.mdc | false |
| Repository appendix | — | 90-repo-specific.mdc | true |
Precedence: A > B > D > C > F > E > G — .cursor/rules/catalog/README.md
Rules reference governance documents — they do not duplicate constitution text.
Skills
Canonical manifest: runtime/manifests/defaults/procedures-manifest.md
| ID | Skill | Tier |
|---|---|---|
skill-architecture | Architecture | Core |
skill-platform | Platform | Core |
skill-laravel | Laravel | Implementation |
skill-ddd | DDD | Implementation |
skill-testing | Testing | Core |
skill-documentation | Documentation | Core |
skill-ui-ux | UI/UX | Implementation |
skill-ai-experience | AI Experience | Specialist |
skill-security | Security | Specialist |
skill-devops | DevOps | Specialist |
Skills never approve architecture or execute Git push.
Agents
Canonical manifest: runtime/manifests/defaults/delegation-manifest.md — .cursor/agents/*.md are definition stubs only.
| Agent | subagent_type | Role |
|---|---|---|
| Architecture | explore (readonly) | Compliance matrix, gap identification |
| Implementation | generalPurpose | Scoped implementation per /phase |
| Testing | shell | Test execution, frozen diff verification |
| Documentation | generalPurpose | Markdown under docs/ |
| UI | generalPurpose | Filament/Blade presentation |
| AI Experience | generalPurpose | Hero/host surfaces — no LLM |
| Security | security-review (readonly) | Diff security review |
| Boundary | explore (readonly) | Module boundary analysis |
| Review | bugbot (readonly) | Pre-submission scope check |
| Release | generalPurpose | Release doc draft — no Git |
Escalation: Subagent → Developer → Architect (RESPONSE_TEMPLATE.md)
Commands
Canonical catalog: runtime/manifests/defaults/workflows-catalog.md
| Command | Category | Invoker |
|---|---|---|
/bootstrap | Verification | Developer + Architect |
/discovery | Lifecycle | Architect |
/spec | Lifecycle | Architect |
/phase | Lifecycle | Architect |
/review | Verification | Developer (+ Review Agent optional) |
/hardening | Lifecycle | Architect → Developer |
/freeze | Lifecycle | Architect |
/release | Release | Documentation Agent + Architect |
/report | Meta | All implementation passes |
/status | Verification | Developer (+ Testing Agent optional) |
Git freeze is not a command — GIT_FREEZE_PROCEDURE.md.
Knowledge architecture
Canonical path: knowledge/ — see knowledge/README.md.
| Area | Purpose | Status |
|---|---|---|
patterns/ | Approved design patterns at freeze baselines | Structure only |
playbooks/ | Operational procedures | Pointers to workflow docs |
recipes/ | Short repeatable task guides | Structure only |
adr/ | Runtime architecture decision records | Structure only |
decision-records/ | EOS engineering decisions | Structure only |
lessons/ | Post-phase retrospectives | Structure only |
assets/ | Reusable checklists and template links | Active pointers |
Intentional grouping under knowledge/ separates operational engineering knowledge from EOS governance manifests at docs/development/ root.
Templates
| Template | Path | Format |
|---|---|---|
| Discovery | templates/discovery.md | Document artifact |
| Specification | templates/specification.md | Document artifact |
| Implementation report | templates/implementation-report.md | Format A (4 sections) or Format B (6 sections) |
| Architecture review | templates/architecture-review.md | Delegates to RESPONSE_TEMPLATE (nine sections — ERP v1.0; EOS v1.0 used eight) |
| Freeze review | templates/freeze-review.md | Format B |
| Release notes | templates/release-notes.md | Platform/EOS release structure |
| Decision record | templates/decision-record.md | ADR structure |
Two implementation report formats only — no third format permitted.
Governance
EOS aligns with parallel authorities by reference only:
| Document | Role |
|---|---|
| PROJECT_CONSTITUTION.md | Runtime constitution |
| COMPANY_CONSTITUTION.md | Corporate constitution |
| PRODUCT_VISION_AND_STRATEGY.md | Product vision |
| LONG_TERM_ROADMAP.md | Platform phase sequence |
| MODULE_BOUNDARIES.md | Frozen platform boundaries |
| PRODUCT_VISION.md | AI experience philosophy |
EOS governs engineering process only — it never modifies runtime modules or frozen platform releases.
Testing
| Suite | Tests | Assertions | Status |
|---|---|---|---|
GovernanceDocumentationTest (architecture docs) | 3 | 33 | Pass |
GovernanceDocumentationTest (EOS docs) | 6 | — | Pass |
EngineeringOperatingSystemIntegrityTest | 12 | — | Pass |
| EOS combined | 23 | 457 | Pass |
Coverage includes: EOS document existence/readability, authority references, asset counts, rule precedence, manifest ↔ catalog ↔ stub consistency, markdown link resolution, report format guards, naming conventions, duplicate regression guards, MCP governance (not enabled).
No runtime module tests — Phase 10 modifies documentation and architecture tests only.
Integrity guards
| Guard | Test / location |
|---|---|
| Governance documentation | GovernanceDocumentationTest |
| EOS asset counts | EngineeringOperatingSystemIntegrityTest::eos_asset_counts_match_canonical_expectations |
| Rule naming and precedence | EngineeringOperatingSystemIntegrityTest::rule_files_follow_naming_convention_and_precedence_documentation |
| Authority chain | EngineeringOperatingSystemIntegrityTest::eos_authority_rule_includes_full_conflict_resolution_chain |
| Skills manifest ↔ SKILL.md | EngineeringOperatingSystemIntegrityTest::skills_manifest_matches_skill_files_and_required_sections |
| Agents manifest ↔ stubs | EngineeringOperatingSystemIntegrityTest::agents_manifest_matches_agent_stubs_and_canonical_ownership |
| Commands catalog ↔ templates | EngineeringOperatingSystemIntegrityTest::commands_catalog_matches_command_templates_and_invokers |
| Markdown cross-references | EngineeringOperatingSystemIntegrityTest::markdown_cross_references_in_eos_assets_resolve |
| Report formats (A + B only) | EngineeringOperatingSystemIntegrityTest::only_two_implementation_report_formats_are_defined |
| Regression (no duplicates) | EngineeringOperatingSystemIntegrityTest::regression_guards_prevent_duplicate_commands_skills_and_agents |
| MCP not enabled | EngineeringOperatingSystemIntegrityTest::mcp_registry_declares_no_enabled_servers_and_points_to_governance |
Canonical expectations: tests/Architecture/Support/EosIntegritySupport.php
Frozen platform verification
| Platform | Tag | Status |
|---|---|---|
| Public Experience | v4.2-public-experience-platform | Frozen — unchanged in Phase 10 |
| Platform UX | v4.1-platform-ux-design-system | Frozen |
| Tracking | v3.12-tracking-platform | Frozen |
| Marketing | v3.11-marketing-platform | Frozen |
| Compliance | v3.10-compliance-platform | Frozen |
| Growth | v3.9-growth-platform | Frozen |
No files under app/Modules/ were modified in Phase 10 delivery.
Pre-freeze verification command:
git diff v4.2-public-experience-platform -- app/Modules/Expected: 0 bytes changed.
Known limitations
.cursor/ gitignored: Engineering assets exist locally; /.cursor/ is in .gitignore until policy enacted at Git freeze — see ENGINEERING_INDEX.md §13.
MCP not enabled: Governance and registry documented; no MCP servers active. Enablement requires explicit Phase 11+ authorization.
Knowledge population: Directory structure and navigation complete; pattern/recipe/lesson content populated after platform freezes prove patterns.
Subagent runtime: Agent definitions are manifest-only; Cursor Task wiring is procedural, not automated configuration.
Phase 10 spec §8.2 paths: Specification shows flat docs/development/{patterns,...}; implementation uses knowledge/ — intentional, documented in knowledge/README.md.
Git freeze (10-9): Pending — tag and commit hash recorded by Developer only.
Future expansion
| Area | Phase | Notes |
|---|---|---|
| MCP enablement | Post-v5.0 | Immediate tier: GitHub, Laravel Docs, PHP Docs — read-only |
| Knowledge patterns/recipes | Per platform freeze | Add after validated at release tag |
| Multi-repo EOS inheritance | Future | Master rules + repository appendix model |
| Developer portal subset | Future | Partner engineering documentation |
| EOS v1.1 amendment | Explicit phase | Additive only — no silent redesign |
Verification commands
# Confirm runtime baseline (unchanged)
git rev-parse v4.2-public-experience-platform^{commit}
# EOS architecture tests (required before freeze)
php artisan test tests/Architecture/GovernanceDocumentationTest.php tests/Architecture/EngineeringOperatingSystemIntegrityTest.php
# Runtime frozen platform spot check
git diff v4.2-public-experience-platform -- app/Modules/Growth app/Modules/Compliance app/Modules/Marketing app/Modules/Tracking app/Modules/PlatformUX app/Modules/PublicExperience
# Full runtime module diff (expect 0 bytes)
git diff v4.2-public-experience-platform -- app/Modules/
# Governance architecture docs (includes EOS extension)
php artisan test tests/Architecture/GovernanceDocumentationTest.phpRelated documentation
| Document | Role |
|---|---|
| MODULE_BOUNDARIES.md | Engineering Operating System freeze entry |
| runtime/specification/archive/phase-10-ai-development-environment-specification.md | Phase 10 design authority |
| AI_DEVELOPMENT_ENVIRONMENT.md | EOS v1.0 methodology root |
| ENGINEERING_INDEX.md | Canonical engineering asset index |
| docs/releases/v4.2-public-experience-platform.md | Runtime baseline |
Engineering Operating System v1.0 — freeze preparation complete. Git freeze: Phase 10-9 — Developer execution only.