Build and Release Playbook:

Shipping ASI-OS Changes Without Regressions or Drama

1.0 Introduction: The Imperative for a Disciplined Release Process

The ASI-OS project is a self-evolving, autonomous cognitive ecosystem. Given this unique nature, an ad-hoc release process introduces unacceptable risks to system stability, safety, and mission alignment. This playbook is the authoritative guide for the build, validation, and deployment of all changes to the ASI-OS platform. Its purpose is to ensure that every enhancement to the system's capabilities is deployed safely, without compromising core stability or deviating from our guiding mission: "Made for a better world."

The system's architecture is founded on principles that demand this level of discipline. Any contribution must be integrated through a process that respects and verifies these core tenets:

• Dual-Architecture System: ASI-OS is strategically separated into the live runtime kernel (Sovereign-Loop) for real-time operations and the offline cognitive ecosystem for skill synthesis. This design allows for aggressive experimentation in the offline environment without jeopardizing the live system. This strict promotion process is our primary defense against contaminating the live, autonomous kernel with an unstable or misaligned capability developed in the offline ecosystem.
• Safety & Governance by Design: Transparency and safety are foundational pillars. This playbook is not merely a technical procedure; it is a governance mechanism. It integrates mandatory checks against key safety components, such as the Safety Governor and immutable Audit Trails, directly into the pre-deployment workflow to ensure every release adheres to our commitment to responsible operation.
• Modularity and Extensibility: The professional src layout encourages contributions by providing clear locations for new skills and agents. However, this modularity requires a rigorous, standardized validation process. This playbook ensures that all new components integrate seamlessly and safely, preserving the integrity of the whole.

This document outlines the practical, step-by-step workflow that translates these high-level principles into a reliable and repeatable release methodology.

2.0 The Contribution Workflow: Ensuring Code Quality and Consistency

A standardized contribution workflow is our first line of defense against regressions and instability. This section details the mandatory process for all developers, ensuring that any code committed to the repository adheres to project standards before it enters the formal release pipeline. Following these steps guarantees consistency and reduces integration friction.

1. Dependency Management: All project dependencies must be installed exclusively using the locked requirements file. This mandate prevents dependency drift, a common source of catastrophic production failures where subtle changes in underlying libraries introduce unpredictable behavior that bypasses the test suite.
2. Modular Contribution: All code contributions must be placed in the appropriate directory within the src layout. This is required to maintain architectural separation and leverage the system's automatic discovery features.

Change Type | Target Directory | Rationale -- | -- | -- New System Capability | src/skills/ | The system loader is designed to automatically discover and register new skills placed here, enabling seamless extensibility. New Agent Behavior | src/agents/ | This isolates the logic for autonomous agents like Professor and Alpha, maintaining clear separation of concerns. Core System Logic | src/core/, src/gpia/, etc. | Changes to the kernel or core intelligence logic require the most stringent code review and testing due to their system-wide impact. Operational Automation | scripts/ | This directory is for maintenance and operational tasks that interact with the src but are not part of the core runtime.

1. Local Validation: Before a pull request is submitted for review, the developer must run the complete test suite locally and verify that all tests pass. A passing local test suite is a non-negotiable prerequisite for code integration. This step ensures that the developer has performed a baseline integrity check, catching obvious errors early and respecting the resources of code reviewers and the release manager.

Adherence to this workflow ensures that code is well-structured and validated before it proceeds to the formal pre-release validation stage.

3.0 Pre-Release Validation Protocol: The Gatekeeper of Stability

This protocol is the most critical phase for preventing regressions and ensuring a smooth deployment. It is a systematic, human-gated series of checks performed on a release candidate to validate its integrity, safety, and functionality in a controlled environment. No release may proceed to deployment without successfully passing every step in this sequence.

1. Execute the Full Test Suite: The release manager must execute the entire test suite in a clean, dedicated environment that mirrors the production configuration. This validates the logical correctness of the codebase and ensures the results are not influenced by local configurations, providing a definitive statement on the code's health.
2. Initiate a Controlled Learning Session: Execute a short, autonomous learning cycle to verify the integration of core cognitive components. Unlike traditional software, a logical error in the cognitive loop between Professor and Alpha could lead not just to a crash, but to the generation of flawed, unsafe skills. This test verifies that the core feedback loop of self-improvement is healthy and operating as an integrated whole.
3. Verify Safety Governor and Audit Trails: Following the learning session, inspect the data/ledger/ directory. This step is a direct validation of the system's governance pillar. You must meticulously verify that every autonomous action taken during the session is recorded in the audit trail and that no action breached the cognitive guardrails defined in src/core/safety_governor.py. A clean ledger is a mandatory gate for release.
4. Clean System Artifacts: Before packaging the release, remove all temporary files generated during testing and validation. This command ensures the final build artifact is created from a pristine source state, eliminating any risk of residual files from test sessions being mistakenly included in the production release.

Once these validation steps are successfully completed, the release candidate is approved for packaging and deployment.

4.0 Standard Build & Release Packaging Procedure

This procedure transforms the validated source code into a versioned, immutable deployment artifact. A standardized build process is essential for ensuring that the exact code that passed validation is what gets deployed, eliminating any possibility of configuration drift or last-minute changes corrupting the release.

1. Code Merge and Tagging: The validated code is merged into the main branch. Immediately following the merge, a new semantic version tag (e.g., v0.2.1) must be created in Git. Git tagging is a non-negotiable step in our release process. It creates a permanent pointer to the exact release commit, providing the absolute traceability required for rapid, reliable rollbacks.
2. Containerization: Build the Docker image using the provided Dockerfile (or Dockerfile.cicd for automated CI/CD environments). Containerization is the ultimate guarantee of consistency, encapsulating the application and its locked dependencies into a single artifact. This eliminates "it works on my machine" problems and ensures the application runs identically across all environments.
3. Create Official Release: Create a formal release on the project's GitHub repository, associating it with the Git tag from the previous step. The release notes must summarize the significant changes and link to the relevant pull requests or issues that were resolved.

With the creation of this versioned artifact, the release is officially packaged and ready for deployment into the live environment.

5.0 Controlled Deployment and Post-Release Monitoring

Deploying the artifact is not the final step of the release process. It marks the beginning of a crucial observation period to confirm that the system is operating as expected in its live Sovereign-Loop mode. A disciplined approach to deployment and monitoring is key to a successful release.

1. Deploy the Artifact: Start the server from the newly built and tagged container image, ensuring it is launched in the correct operational mode.
2. Initial Health Check: Immediately following deployment, review the system's startup logs. You must confirm that the Sovereign-Loop initializes without any errors or critical warnings and that all core services report a healthy status.
3. Monitor Audit Trails: For the first few hours of operation, actively monitor the real-time generation of logs in the data/ledger/ directory. The audit trail is the primary tool for observing the system's autonomous behavior in the live environment. This provides immediate insight into the actions being performed and is the fastest way to detect unexpected behavior.
4. Rollback Procedure: If post-deployment monitoring reveals critical issues, instability, or behavior that violates safety principles, the emergency rollback procedure must be initiated. Stop the current deployment immediately and redeploy the container image associated with the previous stable Git tag.

By adhering to this disciplined, end-to-end process, the team can confidently evolve the ASI-OS platform, shipping powerful changes without regressions or operational drama.