forge-orchestrator 0.1.0b1__tar.gz

forge_orchestrator-0.1.0b1/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Forge
+
+Thank you for contributing to Forge! Forge is an open-source, CLI-first multi-agent orchestration framework for autonomous software development. We welcome contributions from developers helping to fix bugs, improve documentation, and enhance functionality.
+
+## Development Setup
+
+Forge requires Python 3.10 or higher and Git 2.25 or higher. Development and testing are conducted on Linux; for Windows contributors, WSL2 is the recommended environment (Native Windows is not supported due to process management requirements).
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Mathir14/Forge.git
+   cd Forge
+   ```
+
+2. Install Forge in editable mode with development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+3. Verify your installation:
+   ```bash
+   forge --version
+   forge doctor
+   ```
+
+## Repository Structure
+
+- `src/`: Core source code for Forge, including the CLI, agent adapters, stage orchestration, protocol validation, storage, testing engine, and dashboard.
+- `tests/`: Automated test suite containing unit, integration, and regression tests.
+- `docs/`: Project documentation and user guides.
+- `.github/`: GitHub Actions CI workflows, issue templates, and pull request configuration.
+
+## Development Workflow
+
+1. Create a topic branch:
+   ```bash
+   git checkout -b your-branch-name
+   ```
+2. Implement your changes.
+3. Run the test suite to verify changes and prevent regressions.
+4. Update documentation when behavior, commands, or configuration change.
+5. Open a pull request against the main branch with a clear description of your changes.
+
+## Testing
+
+Forge uses `pytest` for automated testing. Run the test suite before submitting changes:
+
+```bash
+# Run the complete test suite
+pytest
+
+# Run tests with verbose output
+pytest -v
+
+# Run a specific test module
+pytest tests/test_config.py
+```
+
+Ensure all tests pass before submitting a pull request.
+
+## Coding Guidelines
+
+- **Small focused commits**: Keep commits atomic and focused on a single change with descriptive messages.
+- **Readable code**: Write clear, readable Python code consistent with surrounding style and conventions.
+- **Preserve backwards compatibility**: Maintain existing CLI behavior, configuration options, and storage formats when practical.
+- **Add tests for new behaviour**: Accompany new features, bug fixes, and adapter updates with appropriate tests.
+- **Keep documentation accurate**: Keep README, user guides, and docstrings aligned with any behavior or interface changes.
+
+## Pull Requests
+
+When submitting a pull request:
+
+- Describe the change and the rationale behind it.
+- Reference any related issues (for example, `Fixes #123`).
+- Keep pull requests focused on a single issue or feature.
+- Ensure the test suite passes locally and CI checks pass.
+
+## Reporting Issues
+
+If you encounter a bug, have a feature suggestion, or want to provide feedback, please open an issue on GitHub using our templates:
+
+- **Bug Report**: For reproducible errors, broken commands, or unexpected behavior.
+- **Feature Request**: For proposing additions or improvements.
+- **Usability Feedback**: For sharing usability experiences and general workflow feedback.
+
+## Releases & Packaging
+
+For maintainers managing package versions, PyPI publication, and Trusted Publishing workflows, refer to the [Release Guide](https://github.com/Mathir14/Forge/blob/master/docs/RELEASING.md).
+

forge_orchestrator-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forge_orchestrator-0.1.0b1/MANIFEST.in

@@ -0,0 +1,20 @@
+# Include essential repository documentation and configuration
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include forge.yaml
+recursive-include docs *
+
+# Only exclude runtime state, repository configuration, caches, and build artifacts
+prune .github
+prune .forge
+prune build
+prune dist
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store
+global-exclude *.swp *.swo *~
+global-exclude .pytest_cache .pytest_cache/*
+global-exclude .ruff_cache .ruff_cache/*

forge_orchestrator-0.1.0b1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: forge-orchestrator
+Version: 0.1.0b1
+Summary: CLI-first multi-agent orchestration framework
+Author: Forge Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mathir14/Forge
+Project-URL: Repository, https://github.com/Mathir14/Forge
+Project-URL: Documentation, https://github.com/Mathir14/Forge/blob/master/docs/USER_GUIDE.md
+Project-URL: Issues, https://github.com/Mathir14/Forge/issues
+Keywords: ai,autonomous,cli,developer-tools,llm,multi-agent,orchestration,playwright,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: web
+Requires-Dist: playwright>=1.30.0; extra == "web"
+Dynamic: license-file
+
+# Forge
+
+Forge is an open-source, CLI-first multi-agent orchestration framework for autonomous, auditable software development. Designed for software engineers and development teams who want to incorporate AI coding agents into real codebases safely, Forge eliminates the risks of unconstrained single-model generation—such as silent bugs, architectural drift, and unverifiable claims—by organizing specialized local CLI agents into a disciplined engineering pipeline with strict separation of concerns, empirical runtime testing, adversarial diff-first review, and complete human-in-the-loop oversight.
+
+## Features
+
+- **Multi-Role Engineering Pipeline**: Coordinates specialized roles in an auditable sequence: **Critic** (`00`), **Architect** (`01`), **Planner** (`02`), **Executor** (`03`), **Tester** (`04`), **Reviewer** (`05`), and post-execution **Critic** (`06`).
+- **CLI-Native Agent Invocation**: Operates directly through installed developer CLI binaries (**OpenCode**, **Google Antigravity** / `agy`, and **OpenAI Codex**) as subprocesses without proprietary cloud API wrappers or token markups.
+- **Empirical Black-Box Testing**: Evaluates running applications through real interfaces (Headless Chromium via Playwright, REST/GraphQL APIs, CLI binaries, Library imports) under process group supervision (`RuntimeSupervisor`), collecting viewport screenshots, telemetry logs, and executable reproduction scripts.
+- **Diff-First Adversarial Review**: Change-centric quality gate where the Git diff is the primary review artifact. The Reviewer validates Executor claims against actual codebase changes and empirical test evidence before granting approval.
+- **Autonomous Self-Repair Loop**: In `forge auto`, automatically iterates between the Executor, Tester, and Reviewer. If tests fail or changes are requested, structured issue feedback is fed back into subsequent implementation attempts until approved or retry limits are reached.
+- **Interactive Checkpoints & Resumption**: Run interactively with step-by-step confirmation checkpoints (`forge run`) or resume any previous run seamlessly (`--run run-XXX`), automatically skipping already completed stages.
+- **Project Knowledge Base (PKB)**: Automatically discovers and tracks persistent repository knowledge across runs in `.forge/knowledge/` (`architecture.yaml`, `features.yaml`, `decisions.yaml`, `unresolved.yaml`) with role-based permissions and human locking.
+- **Terminal User Interface Dashboard**: Interactive terminal dashboard (`forge dashboard`) to monitor live runs or inspect historical runs with timeline navigation, streaming console output, stage artifacts, test evidence, and knowledge base browser.
+- **Git Safety & Change Attribution**: Captures unified diffs with automatic filtering of `.forge/` runtime data and `.env*` secrets, intelligently attributing changes to avoid committing mixed-ownership files containing pre-existing user edits.
+- **Process-Level Run Locking**: Kernel-backed exclusive run locking (`flock`) prevents concurrent process conflicts on the same run directory with automatic stale-lock recovery.
+
+## Requirements
+
+- **Python**: `>= 3.10`
+- **Git**: `>= 2.25` installed and available in `PATH`
+- **Supported Agent CLIs** (at least one installed and authenticated):
+  - **OpenCode** (`opencode`)
+  - **Google Antigravity** (`agy` or `antigravity`)
+  - **OpenAI Codex** (`codex`)
+- **Optional for Web Testing**:
+  - `playwright` (`pip install playwright && playwright install chromium`)
+
+## Platform Support
+
+Forge is primarily developed and tested on Linux. For Windows users, WSL2 is the recommended environment.
+
+| Platform | Status | Notes |
+| :--- | :--- | :--- |
+| **Linux** | Supported | Primary development and testing platform. |
+| **WSL2** | Supported (Recommended for Windows) | Full compatibility with all pipeline stages and process supervision. |
+| **macOS** | Supported | Compatible with POSIX process isolation and standard pipeline execution. |
+| **Native Windows** | Not Supported | Forge relies on Linux/WSL-compatible process management for runtime supervision and testing. |
+
+## Installation
+ 
+Install Forge from PyPI:
+ 
+```bash
+pip install forge-orchestrator
+```
+ 
+### Development Installation
+ 
+To contribute to Forge or install directly from the source repository:
+ 
+```bash
+git clone https://github.com/Mathir14/Forge.git
+cd Forge
+pip install -e ".[dev]"
+```
+
+Verify your installation:
+
+```bash
+forge --version
+forge doctor
+```
+
+## Quick Start
+
+Get started with Forge in under 5 minutes:
+
+```bash
+# 1. Initialize Forge prompt templates and configuration in your project
+forge init
+
+# 2. Check installed CLI tools, git state, and stage configurations
+forge doctor
+
+# 3. Perform a standalone codebase audit for technical debt and vulnerabilities
+forge critic "Audit authentication system and error handling"
+
+# 4. Implement a task with step-by-step confirmation checkpoints
+forge run "Add /healthz JSON endpoint with uptime and git commit SHA"
+
+# 5. Inspect the execution artifacts and timeline in the interactive dashboard
+forge dashboard
+```
+
+To run the pipeline completely unattended with autonomous self-repair:
+
+```bash
+forge auto "Implement rate limiting middleware using token bucket algorithm" --auto-commit
+```
+
+## Supported Adapters
+
+Forge connects to installed CLI tools using native adapters. View all registered adapters and their capabilities at any time using `forge adapters`:
+
+| Adapter | Binary | Default Model | Prompt Transport | Core Capabilities |
+| :--- | :--- | :--- | :--- | :--- |
+| `opencode` | `opencode` | Provider default | `stdin` | `code_read`, `code_edit`, `shell`, `git`, `structured_output`, `custom_flags` |
+| `antigravity` (`agy`) | `agy` or `antigravity` | `gemini-3.7-flash-high` | `-p` flag | `code_read`, `code_edit`, `shell`, `git`, `long_running`, `structured_output`, `custom_flags` |
+| `codex` | `codex` | `gpt-5.6-terra` | `stdin` (`-`) | `code_read`, `code_edit`, `shell`, `git`, `long_running`, `structured_output`, `tool_calling`, `custom_flags` |
+
+## Documentation
+
+For full operational details, configuration schemas, CLI command reference, testing engine guides, and troubleshooting workflows, consult the [Complete User Guide](https://github.com/Mathir14/Forge/blob/master/docs/USER_GUIDE.md).
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](https://github.com/Mathir14/Forge/blob/master/CONTRIBUTING.md) for guidelines on development environment setup, coding conventions, and submitting pull requests.
+
+## License
+
+Forge is licensed under the [MIT License](https://github.com/Mathir14/Forge/blob/master/LICENSE).
+

forge_orchestrator-0.1.0b1/README.md

@@ -0,0 +1,113 @@
+# Forge
+
+Forge is an open-source, CLI-first multi-agent orchestration framework for autonomous, auditable software development. Designed for software engineers and development teams who want to incorporate AI coding agents into real codebases safely, Forge eliminates the risks of unconstrained single-model generation—such as silent bugs, architectural drift, and unverifiable claims—by organizing specialized local CLI agents into a disciplined engineering pipeline with strict separation of concerns, empirical runtime testing, adversarial diff-first review, and complete human-in-the-loop oversight.
+
+## Features
+
+- **Multi-Role Engineering Pipeline**: Coordinates specialized roles in an auditable sequence: **Critic** (`00`), **Architect** (`01`), **Planner** (`02`), **Executor** (`03`), **Tester** (`04`), **Reviewer** (`05`), and post-execution **Critic** (`06`).
+- **CLI-Native Agent Invocation**: Operates directly through installed developer CLI binaries (**OpenCode**, **Google Antigravity** / `agy`, and **OpenAI Codex**) as subprocesses without proprietary cloud API wrappers or token markups.
+- **Empirical Black-Box Testing**: Evaluates running applications through real interfaces (Headless Chromium via Playwright, REST/GraphQL APIs, CLI binaries, Library imports) under process group supervision (`RuntimeSupervisor`), collecting viewport screenshots, telemetry logs, and executable reproduction scripts.
+- **Diff-First Adversarial Review**: Change-centric quality gate where the Git diff is the primary review artifact. The Reviewer validates Executor claims against actual codebase changes and empirical test evidence before granting approval.
+- **Autonomous Self-Repair Loop**: In `forge auto`, automatically iterates between the Executor, Tester, and Reviewer. If tests fail or changes are requested, structured issue feedback is fed back into subsequent implementation attempts until approved or retry limits are reached.
+- **Interactive Checkpoints & Resumption**: Run interactively with step-by-step confirmation checkpoints (`forge run`) or resume any previous run seamlessly (`--run run-XXX`), automatically skipping already completed stages.
+- **Project Knowledge Base (PKB)**: Automatically discovers and tracks persistent repository knowledge across runs in `.forge/knowledge/` (`architecture.yaml`, `features.yaml`, `decisions.yaml`, `unresolved.yaml`) with role-based permissions and human locking.
+- **Terminal User Interface Dashboard**: Interactive terminal dashboard (`forge dashboard`) to monitor live runs or inspect historical runs with timeline navigation, streaming console output, stage artifacts, test evidence, and knowledge base browser.
+- **Git Safety & Change Attribution**: Captures unified diffs with automatic filtering of `.forge/` runtime data and `.env*` secrets, intelligently attributing changes to avoid committing mixed-ownership files containing pre-existing user edits.
+- **Process-Level Run Locking**: Kernel-backed exclusive run locking (`flock`) prevents concurrent process conflicts on the same run directory with automatic stale-lock recovery.
+
+## Requirements
+
+- **Python**: `>= 3.10`
+- **Git**: `>= 2.25` installed and available in `PATH`
+- **Supported Agent CLIs** (at least one installed and authenticated):
+  - **OpenCode** (`opencode`)
+  - **Google Antigravity** (`agy` or `antigravity`)
+  - **OpenAI Codex** (`codex`)
+- **Optional for Web Testing**:
+  - `playwright` (`pip install playwright && playwright install chromium`)
+
+## Platform Support
+
+Forge is primarily developed and tested on Linux. For Windows users, WSL2 is the recommended environment.
+
+| Platform | Status | Notes |
+| :--- | :--- | :--- |
+| **Linux** | Supported | Primary development and testing platform. |
+| **WSL2** | Supported (Recommended for Windows) | Full compatibility with all pipeline stages and process supervision. |
+| **macOS** | Supported | Compatible with POSIX process isolation and standard pipeline execution. |
+| **Native Windows** | Not Supported | Forge relies on Linux/WSL-compatible process management for runtime supervision and testing. |
+
+## Installation
+ 
+Install Forge from PyPI:
+ 
+```bash
+pip install forge-orchestrator
+```
+ 
+### Development Installation
+ 
+To contribute to Forge or install directly from the source repository:
+ 
+```bash
+git clone https://github.com/Mathir14/Forge.git
+cd Forge
+pip install -e ".[dev]"
+```
+
+Verify your installation:
+
+```bash
+forge --version
+forge doctor
+```
+
+## Quick Start
+
+Get started with Forge in under 5 minutes:
+
+```bash
+# 1. Initialize Forge prompt templates and configuration in your project
+forge init
+
+# 2. Check installed CLI tools, git state, and stage configurations
+forge doctor
+
+# 3. Perform a standalone codebase audit for technical debt and vulnerabilities
+forge critic "Audit authentication system and error handling"
+
+# 4. Implement a task with step-by-step confirmation checkpoints
+forge run "Add /healthz JSON endpoint with uptime and git commit SHA"
+
+# 5. Inspect the execution artifacts and timeline in the interactive dashboard
+forge dashboard
+```
+
+To run the pipeline completely unattended with autonomous self-repair:
+
+```bash
+forge auto "Implement rate limiting middleware using token bucket algorithm" --auto-commit
+```
+
+## Supported Adapters
+
+Forge connects to installed CLI tools using native adapters. View all registered adapters and their capabilities at any time using `forge adapters`:
+
+| Adapter | Binary | Default Model | Prompt Transport | Core Capabilities |
+| :--- | :--- | :--- | :--- | :--- |
+| `opencode` | `opencode` | Provider default | `stdin` | `code_read`, `code_edit`, `shell`, `git`, `structured_output`, `custom_flags` |
+| `antigravity` (`agy`) | `agy` or `antigravity` | `gemini-3.7-flash-high` | `-p` flag | `code_read`, `code_edit`, `shell`, `git`, `long_running`, `structured_output`, `custom_flags` |
+| `codex` | `codex` | `gpt-5.6-terra` | `stdin` (`-`) | `code_read`, `code_edit`, `shell`, `git`, `long_running`, `structured_output`, `tool_calling`, `custom_flags` |
+
+## Documentation
+
+For full operational details, configuration schemas, CLI command reference, testing engine guides, and troubleshooting workflows, consult the [Complete User Guide](https://github.com/Mathir14/Forge/blob/master/docs/USER_GUIDE.md).
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](https://github.com/Mathir14/Forge/blob/master/CONTRIBUTING.md) for guidelines on development environment setup, coding conventions, and submitting pull requests.
+
+## License
+
+Forge is licensed under the [MIT License](https://github.com/Mathir14/Forge/blob/master/LICENSE).
+

forge_orchestrator-0.1.0b1/docs/RELEASING.md

@@ -0,0 +1,150 @@
+# Forge Production Staged Release Guide
+
+This document details the production-grade, staged release process for `forge-orchestrator`.
+
+---
+
+## 1. Core Principles
+
+- **Zero Local Publishing**: No developer publishes from local machines.
+- **Zero API Tokens**: No API tokens or passwords are stored in GitHub Secrets.
+- **Trusted Publishing (OIDC) Only**: Cryptographic, short-lived OpenID Connect token minting.
+- **Single Build Guarantee**: Wheel and sdist are built once, validated once, uploaded to TestPyPI, and subsequently deployed to production PyPI. **Artifacts are never rebuilt between staging and production.**
+- **Automatic Smoke Testing**: The pipeline automatically installs the freshly staged package from TestPyPI into a clean container and executes import and CLI diagnostics before requesting production approval.
+- **Environment Gatekeeper**: Production PyPI publication requires explicit manual approval in GitHub by designated maintainers.
+- **Automated GitHub Release**: Once PyPI publication succeeds, a GitHub Release is automatically published with release notes and distribution assets attached.
+
+---
+
+## 2. Release Architecture & Flow
+
+```
+Developer
+  │
+  ├─ 1. Bump version in pyproject.toml & src/forge/__init__.py
+  ├─ 2. Commit changes
+  ├─ 3. Tag (e.g., git tag -a v0.1.0b1 -m "Release v0.1.0b1")
+  └─ 4. Push tag to GitHub
+        │
+GitHub Actions (.github/workflows/release.yml)
+  │
+  ├─ Job 1: test-and-build
+  │    ├─ Validate version tag format (PEP 440)
+  │    ├─ Run full pytest suite (540+ tests)
+  │    ├─ Single Build: build wheel and sdist (python -m build)
+  │    ├─ Validate with twine check --strict dist/*
+  │    └─ Upload dist/ artifacts to workflow run storage
+  │
+  ├─ Job 2: publish-testpypi (Environment: testpypi)
+  │    ├─ Download dist/ artifacts
+  │    └─ Publish to TestPyPI via pypa/gh-action-pypi-publish (OIDC)
+  │
+  ├─ Job 3: smoke-test-testpypi
+  │    ├─ Poll and install forge-orchestrator FROM TestPyPI (20 attempts x 10s)
+  │    ├─ Verify import: python -c "import forge; print(forge.__version__)"
+  │    ├─ Verify: forge --version
+  │    ├─ Verify: forge --help
+  │    └─ Verify: forge doctor
+  │
+  ├─ Job 4: publish-pypi (Environment: pypi)
+  │    ├─ 🛑 PAUSES: Waits for maintainer review & approval
+  │    ├─ Download EXACT SAME dist/ artifacts (No Rebuild)
+  │    └─ Publish to Production PyPI via pypa/gh-action-pypi-publish (OIDC)
+  │
+  └─ Job 5: create-github-release
+       ├─ Download EXACT SAME dist/ artifacts
+       └─ Auto-publish GitHub Release with assets via gh release create
+```
+
+---
+
+## 3. One-Time Setup: PyPI & TestPyPI Trusted Publishing (OIDC)
+
+### A. Production PyPI Setup
+
+1. Log into your account at [pypi.org](https://pypi.org).
+2. If `forge-orchestrator` is not yet published:
+   - Go to [PyPI Publishing (Add Pending Publisher)](https://pypi.org/manage/account/publishing/).
+   - Select **GitHub**.
+   - **PyPI Project Name**: `forge-orchestrator`
+   - **Owner**: `Mathir14`
+   - **Repository name**: `Forge`
+   - **Workflow name**: `release.yml`
+   - **Environment name**: `pypi`
+3. If already registered:
+   - Go to **Project Settings** ➔ **Publishing** ➔ **Add a new publisher** with the above details.
+
+### B. TestPyPI Setup
+
+1. Log into your account at [test.pypi.org](https://test.pypi.org).
+2. Go to [TestPyPI Publishing (Add Pending Publisher)](https://test.pypi.org/manage/account/publishing/).
+   - Select **GitHub**.
+   - **PyPI Project Name**: `forge-orchestrator`
+   - **Owner**: `Mathir14`
+   - **Repository name**: `Forge`
+   - **Workflow name**: `release.yml`
+   - **Environment name**: `testpypi`
+
+### C. GitHub Repository Environments Setup
+
+In the GitHub repository (`https://github.com/Mathir14/Forge`):
+
+1. Go to **Settings** ➔ **Environments**.
+2. Create environment `testpypi`:
+   - No approval restrictions needed (automated staging).
+3. Create environment `pypi`:
+   - Enable **Required reviewers**.
+   - Select authorized maintainers who must sign off before any production PyPI deployment.
+   - *(Optional)* Set **Deployment branches/tags** to `v*`.
+
+---
+
+## 4. Maintainer Release Process
+
+To cut a new release:
+
+### Step 1: Bump Version & Validate Locally
+
+Update the version in:
+- `pyproject.toml` (e.g. `version = "0.1.0b1"`)
+- `src/forge/__init__.py` (e.g. `__version__ = "0.1.0b1"`)
+
+Run local tests to confirm:
+```bash
+pytest
+```
+
+### Step 2: Commit and Tag
+
+```bash
+git commit -am "chore: release v0.1.0b1"
+git push origin master
+
+git tag -a v0.1.0b1 -m "Release v0.1.0b1"
+git push origin v0.1.0b1
+```
+
+### Step 3: Monitor Staged Release in GitHub Actions
+
+1. The `Staged Release` workflow triggers on the tag push.
+2. It validates the tag format, runs the full test suite, builds distributions, uploads to TestPyPI, and runs automated smoke tests.
+3. Once smoke tests succeed, the workflow pauses at `publish-pypi` with status `Waiting for review`.
+
+### Step 4: Approve Production Release
+
+1. In the GitHub Actions run page, review the TestPyPI smoke test logs.
+2. Click **Review deployments** ➔ Select `pypi` ➔ Click **Approve and deploy**.
+3. The exact same wheel and sdist files are immediately deployed to [pypi.org/p/forge-orchestrator](https://pypi.org/p/forge-orchestrator).
+4. GitHub Actions then automatically creates and publishes the GitHub Release with generated release notes and attached distribution assets.
+
+---
+
+## 5. PEP 440 Versioning Reference
+
+| Release Phase | PEP 440 Version Format | Git Tag | Target |
+| :--- | :--- | :--- | :--- |
+| **Development** | `0.2.0.dev1` | `v0.2.0-dev1` | TestPyPI |
+| **Alpha** | `0.2.0a1` | `v0.2.0a1` | TestPyPI / PyPI |
+| **Beta** | `0.2.0b1` | `v0.2.0b1` | TestPyPI / PyPI |
+| **Release Candidate** | `0.2.0rc1` | `v0.2.0rc1` | TestPyPI / PyPI |
+| **Final / Stable** | `0.2.0` | `v0.2.0` | PyPI |