Update Orchestrator README (MVP Scope + Interface)

.github/pull_request_template.md

@@ -1,10 +1,7 @@
-## What does this PR change?
--
-
-## Which module?
--
+## Summary
+Explain what changed and why.
 
 ## Checklist
-- [ ] README updated (how to run + demo)
-- [ ] Inputs/outputs documented
-- [ ] No credentials / private data
+- [ ] No secrets/credentials committed
+- [ ] Docs updated (if needed)
+- [ ] Tests added/updated (if applicable)

.gitignore

@@ -144,6 +144,7 @@ ENV/
 env.bak/
 venv.bak/
 
+
 # Spyder project settings
 .spyderproject
 .spyproject
@@ -236,5 +237,17 @@ __pycache__/
 .DS_Store
 Thumbs.db
 
+# Monitor module generated outputs
+modules/monitor/data/
+modules/monitor/deliverables/
+modules/monitor/embedding/
+modules/monitor/*.log
+modules/monitor/*.dat
+modules/monitor/**/*.db
+modules/monitor/**/*.db-journal
+
 OpenPolicyStack/
 
+# Allow example env templates (must be AFTER any .env / .env.* ignores)
+!.env.example
+!**/.env.example

ADRIAN_CON_THESIS_SCOPE.md

@@ -0,0 +1,46 @@
+# Thesis Scope – Adrian Con García
+
+This repository is part of the broader OpenPolicyStack project.  
+This document clarifies the scope of the work developed and evaluated in the corresponding thesis.
+
+## Scope of Contribution
+
+The thesis focuses specifically on the design, implementation, and evaluation of the **orchestration layer** and its integration interface.
+
+The evaluated software artifact consists of:
+
+- `modules/orchestrator/` → central orchestration service (primary contribution)
+- `modules/integration-pilot/` → controlled validation module used to test integration and evaluation conditions
+- `compose.yaml` → minimal deployment configuration used to run the system
+
+Other modules present in the repository are part of the wider collaborative project and are **not part of the evaluated contribution**.
+
+## Evaluated System State
+
+The version contained in this branch corresponds to the **instrumented evaluation state** of the system.
+
+Starting from a working end-to-end orchestration prototype (baseline MVP), the system was incrementally extended to enable empirical evaluation of the following properties:
+
+- reproducibility
+- traceability
+- artifact integrity
+- execution trace reconstruction
+- failure handling robustness
+
+These properties were evaluated through a structured experimental framework (E1–E5) as described in the thesis.
+
+## Important Notes
+
+- The orchestrator was extended with structured metadata capture and hashing mechanisms to support empirical validation.
+- The integration-pilot module was intentionally used as a controlled environment to isolate and test orchestration behavior before integrating external modules.
+- A controlled failure trigger used exclusively for evaluation purposes has been disabled in this version.
+
+## How to Navigate
+
+For reviewers interested in the evaluated artifact:
+
+1. Start with: `modules/orchestrator/`
+2. See integration behavior in: `modules/integration-pilot/`
+3. Use `compose.yaml` to understand how services are connected
+
+This subset of the repository corresponds to the system evaluated in the thesis.

compose.yaml

@@ -0,0 +1,81 @@
+name: openpolicystack-pilot
+
+services:
+  orchestrator:
+    build:
+      context: ./modules/orchestrator
+      dockerfile: Dockerfile
+    image: openpolicystack/orchestrator:dev
+    env_file:
+      - ./modules/orchestrator/.env
+    environment:
+      OPS_ENV: dev
+      OPS_MODULE_NAME: orchestrator
+      OPS_PORT: 8080
+      OPS_LOG_LEVEL: INFO
+      OPS_ARTIFACT_ROOT: /var/openpolicystack/artifacts
+      ORCHESTRATOR__SQLITE_PATH: /var/openpolicystack/metadata/orchestrator.db
+      ORCHESTRATOR__INTEGRATION_PILOT_URL: http://integration-pilot:8080
+    ports:
+      - "8100:8080"
+    volumes:
+      - ops-artifacts:/var/openpolicystack/artifacts
+      - ops-metadata:/var/openpolicystack/metadata
+    networks:
+      - ops-core
+    depends_on:
+      - integration-pilot
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health')"
+        ]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+
+  integration-pilot:
+    build:
+      context: ./modules/integration-pilot
+      dockerfile: Dockerfile
+    image: openpolicystack/integration-pilot:dev
+    env_file:
+      - ./modules/integration-pilot/.env
+    environment:
+      OPS_ENV: dev
+      OPS_MODULE_NAME: integration-pilot
+      OPS_PORT: 8080
+      OPS_LOG_LEVEL: INFO
+      OPS_ARTIFACT_ROOT: /var/openpolicystack/artifacts
+      OPS_ORCHESTRATOR_URL: http://orchestrator:8080
+      PILOT_MODULE_VERSION: 0.1.1
+    ports:
+      - "8101:8080"
+    volumes:
+      - ops-artifacts:/var/openpolicystack/artifacts
+    networks:
+      - ops-core
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health')"
+        ]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+
+networks:
+  ops-core:
+    driver: bridge
+
+volumes:
+  ops-artifacts:
+  ops-metadata:

deploy/README.md

@@ -0,0 +1,108 @@
+# OpenPolicyStack – Deployment & Validation Guide
+
+## Purpose
+This folder contains deployment-related artifacts for OpenPolicyStack, including the full architecture skeleton and basic validation instructions.
+
+At this stage, the system is validated through a **minimal runnable pilot stack** composed of:
+- `orchestrator` (system coordinator)
+- `integration-pilot` (reference module)
+
+---
+
+## Deployment Files
+
+- `../compose.yaml`  
+  → Current **runnable pilot stack** (validated baseline)
+
+- `compose.target-skeleton.yaml`  
+  → **Full intended architecture** (not yet fully runnable; used as integration target)
+
+---
+
+## Pilot Validation Procedure
+
+Run all commands from the repository root:
+
+```bash
+docker compose config
+docker compose build
+docker compose up -d
+docker compose ps
+```
+Test the orchestrator:
+
+```
+curl http://localhost:8100/health
+```
+
+Execute a sample workflow:
+
+```
+curl-X POST http://localhost:8100/execute \
+-H"Content-Type: application/json" \
+-d'{"test":"hello","source":"vm-check"}'
+```
+
+Inspect shared artifacts:
+
+```
+docker compose exec orchestratorls-R /var/openpolicystack/artifacts
+```
+
+Inspect metadata:
+
+```
+docker compose exec orchestratorls-R /var/openpolicystack/metadata
+```
+
+---
+
+## Expected Outcome
+
+A successful validation should confirm:
+
+- Both containers build and run successfully
+- Both services report **healthy** status
+- Orchestrator responds on `http://localhost:8100`
+- Orchestrator can resolve `integration-pilot` via Docker network
+- Shared artifact volume is written and visible across containers
+- Metadata database (`orchestrator.db`) is created
+
+---
+
+## Current Scope
+
+The pilot validates:
+
+- Basic orchestration flow (`/execute`)
+- Service-to-service communication
+- Shared artifact storage
+- Metadata persistence (SQLite)
+- Contract-compliant module execution
+
+Not yet covered:
+
+- Multi-module integration
+- Real module onboarding from teammates
+- Full evaluation framework (E1–E5)
+- Production deployment considerations
+
+---
+
+## Common Issues
+
+- Missing `.env` files (must be created from `.env.example`)
+- Incorrect file paths or build contexts
+- Missing or incorrect Dockerfile
+- Wrong application entrypoint (`app.main`)
+- Running commands outside repo root
+
+---
+
+## Next Steps
+
+- Expand orchestrator metadata layer (`runs`, `module_calls`, `artifacts`)
+- Strengthen determinism and reproducibility guarantees
+- Introduce evaluation tests (E1–E5)
+- Onboard first real module into the stack
+- Progressively align with `compose.target-skeleton.yaml`