[AISOS-2002] Forge documentation

.github/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI
 
 on:
   pull_request:
+    types: [opened, synchronize, edited]
     branches:
       - main
 
@@ -48,7 +49,7 @@ jobs:
           python-version: "3.11"
 
       - name: Install dependencies
-        run: uv sync --frozen --extra dev
+        run: uv sync --frozen --extra dev --extra docs
 
       - name: Run unit tests
         env:
@@ -57,3 +58,26 @@ jobs:
           JIRA_USER_EMAIL: dummy@example.com
           GITHUB_TOKEN: dummy
         run: uv run pytest tests/unit/ -q
+
+  doc-freshness:
+    name: Doc Freshness
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Check documentation freshness
+        run: |
+          python scripts/check-doc-freshness.py --base origin/${{ github.base_ref }} --head HEAD --verbose

.github/workflows/deploy-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'zensical.toml'
+      - 'zensical.config.json'
+      - 'CONTRIBUTING.md'
+      - 'README.md'
+      - 'skills/README.md'
+  workflow_dispatch:
+
+# Restrict permissions to only what's required for checking out code
+# and writing/deploying the documentation build to the gh-pages branch.
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build & Deploy Portal
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for ghp-import to work properly with full history
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra docs
+
+      - name: Build documentation
+        run: uv run zensical build
+
+      - name: Configure Git User
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          uv run ghp-import -n -p -f site

docs/architecture.md

@@ -0,0 +1,45 @@
+# Architecture
+
+This document describes the high-level architecture of Forge, an AI-powered SDLC orchestrator that automates software development workflows using LangGraph, FastAPI, and Claude.
+
+## System Overview
+
+Forge is designed as a distributed, asynchronous system composed of several core modules:
+
+```mermaid
+graph TB
+    API[FastAPI Server] --> Queue[Redis Streams / Queue]
+    Queue --> Worker[Queue Worker]
+    Worker --> Graph[LangGraph Orchestrator]
+    Graph --> State[Redis State Store]
+    Graph --> Jira[Jira Integration]
+    Graph --> GitHub[GitHub Integration]
+    Graph --> Sandbox[Podman Sandbox]
+    Sandbox --> DeepAgents[Deep Agents Engine]
+```
+
+## Core Modules
+
+### 1. API Server (`src/forge/api/`)
+The entry point for external webhooks. It handles webhook payloads from Jira (issue updates, comment events) and GitHub (PR comments, push events, checks) and pushes them to Redis Streams.
+
+### 2. Event Queue (`src/forge/queue/`)
+An event queuing system based on Redis Streams. It provides asynchronous processing, reliable delivery guarantees, and backpressure management.
+
+### 3. Queue Worker & Worker Logic (`src/forge/orchestrator/worker.py`)
+Consumers that pull events from Redis Streams, resolve them to specific LangGraph state instances, and resume the corresponding workflow execution.
+
+### 4. LangGraph Orchestrator (`src/forge/orchestrator/`)
+Defines the workflow graph using LangGraph. The orchestrator:
+- Manages state checkpoints in Redis.
+- Governs transitions between nodes (PRD generation, Spec generation, Epic decomposition, Task execution, PR creation, CI fix loop).
+- Implements human-in-the-loop approval gates using Jira labels and GitHub review approval markers.
+
+### 5. Workspace & Sandbox (`src/forge/sandbox/`)
+Executes code implementation and testing in ephemeral Podman containers. It prepares a isolated local Git repository workspace, runs the implementation task via Deep Agents, verifies code changes, and commits them locally.
+
+## Design Principles
+
+- **State Persistence:** Every node in the workflow graph commits its state to Redis. If the process is restarted, the state is safely restored and the workflow resumes where it was left off.
+- **Security Isolation:** Code changes are performed in container sandboxes without network access, shielding the core system from unauthorized or accidental resource manipulation.
+- **Asymmetric Human Approval:** Automatic planning is interleaved with explicit approval gates. Humans can inspect generated PRDs or Specs and request revisions by leaving comments.