release: version 0.9.4 🚀

.gitea/workflows/build_release.yml

@@ -4,6 +4,7 @@ permissions:
 
 env:
   SKIP_MAKE_SETUP_CHECK: 'true'
+  DOCKER_API_VERSION: '1.43'
 
 on:
   push:
@@ -49,11 +50,15 @@ jobs:
         fi
     - name: Login to Gitea container registry
       uses: docker/login-action@v3
+      env:
+        DOCKER_API_VERSION: ${{ env.DOCKER_API_VERSION }}
       with:
         username: gitearobot
         password: ${{ secrets.PACKAGE_GITEA_PAT }}
         registry: git.disi.dev
     - name: Build and publish
+      env:
+        DOCKER_API_VERSION: ${{ env.DOCKER_API_VERSION }}
       run: |
         REPOSITORY_OWNER=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $1}' | tr '[:upper:]' '[:lower:]')
         REPOSITORY_NAME=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $2}' | tr '-' '_')

.gitignore

@@ -0,0 +1,2 @@
+sqlite.db
+.nicegui/

Containerfile

@@ -40,4 +40,4 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:8000/health || exit 1
 
 # Run application
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]"]
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

HISTORY.md

@@ -5,10 +5,206 @@ Changelog
 (unreleased)
 ------------
 
+Fix
+~~~
+- Add commit retry, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.9.3 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Better home assistant integration, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.2 (2026-04-11)
+------------------
+
+Fix
+~~~
+- UI improvements and prompt hardening, refs NOISSUE. [Simon
+  Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.1 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Better repo name generation, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.0 (2026-04-11)
+------------------
+- Feat: editable guardrails, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.8.0 (2026-04-11)
+------------------
+- Feat: better dashboard reloading mechanism, refs NOISSUE. [Simon
+  Diesenreiter]
+- Feat: add explicit workflow steps and guardrail prompts, refs NOISSUE.
+  [Simon Diesenreiter]
+
+
+0.7.1 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Add additional deletion confirmation, refs NOISSUE. [Simon
+  Diesenreiter]
+
+Other
+~~~~~
+
+
+0.7.0 (2026-04-10)
+------------------
+- Feat: gitea issue integration, refs NOISSUE. [Simon Diesenreiter]
+- Feat: better history data, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.6.5 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Better n8n workflow, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.4 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Add Telegram helper functions, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.3 (2026-04-10)
+------------------
+
+Fix
+~~~
+- N8n workflow generation, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.2 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Fix Quasar layout issues, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.1 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Fix commit for version push, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+- Chore: add more health info for n8n, refs NOISSUE. [Simon
+  Diesenreiter]
+
+
+0.6.0 (2026-04-10)
+------------------
+- Feat(api): expose database target in health refs NOISSUE. [Simon
+  Diesenreiter]
+- Fix(db): prefer postgres config in production refs NOISSUE. [Simon
+  Diesenreiter]
+
+
+0.5.0 (2026-04-10)
+------------------
+- Feat(dashboard): expose repository urls refs NOISSUE. [Simon
+  Diesenreiter]
+- Feat(factory): serve dashboard at root and create project repos refs
+  NOISSUE. [Simon Diesenreiter]
+
+
+0.4.1 (2026-04-10)
+------------------
+- Fix(ci): pin docker api version for release builds refs NOISSUE.
+  [Simon Diesenreiter]
+
+
+0.4.0 (2026-04-10)
+------------------
+- Chore(git): ignore local sqlite database refs NOISSUE. [Simon
+  Diesenreiter]
+- Feat(factory): implement db-backed dashboard and workflow automation
+  refs NOISSUE. [Simon Diesenreiter]
+
+
+0.3.6 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Rename gitea workflow, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.5 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Some cleanup, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.4 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Fix database init, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.3 (2026-04-04)
+------------------
+
 Fix
 ~~~
 - Fix runtime errors, refs NOISSUE. [Simon Diesenreiter]
 
+Other
+~~~~~
+
 
 0.3.2 (2026-04-04)
 ------------------

Makefile

@@ -1,5 +1,7 @@
 .ONESHELL:
 
+DOCKER_API_VERSION ?= 1.43
+
 .PHONY: issetup
 issetup:
 	@[ -f .git/hooks/commit-msg ] || [ -z ${SKIP_MAKE_SETUP_CHECK+x} ] || (echo "You must run 'make setup' first to initialize the repo!" && exit 1)
@@ -42,7 +44,7 @@ release: issetup         ## Create a new tag for release.
 
 .PHONY: build
 build: issetup          ## Create a new tag for release.
-	@docker build -t ai-software-factory:$(cat ai-software-factory/VERSION) -f Containerfile .
+	@DOCKER_API_VERSION=$(DOCKER_API_VERSION) docker build -t ai-software-factory:$(cat ai_software_factory/VERSION) -f Containerfile .
 
 # This project has been generated from rochacbruno/python-project-template
 #igest__ = 'rochacbruno'

README.md

@@ -6,7 +6,7 @@ Automated software generation service powered by Ollama LLM. This service allows
 
 - **Telegram Integration**: Receive software requests via Telegram bot
 - **Ollama LLM**: Uses Ollama-hosted models for code generation
-- **Git Integration**: Automatically commits code to gitea
+- **Git Integration**: Creates a dedicated Gitea repository per generated project inside your organization
 - **Pull Requests**: Creates PRs for user review before merging
 - **Web UI**: Beautiful dashboard for monitoring project progress
 - **n8n Workflows**: Bridges Telegram with LLMs via n8n webhooks
@@ -48,10 +48,21 @@ OLLAMA_URL=http://localhost:11434
 OLLAMA_MODEL=llama3
 
 # Gitea
+# Host-only values such as git.disi.dev are normalized to https://git.disi.dev.
 GITEA_URL=https://gitea.yourserver.com
-GITEA_TOKEN= analyze your_gitea_api_token
+GITEA_TOKEN=your_gitea_api_token
 GITEA_OWNER=ai-software-factory
-GITEA_REPO=ai-software-factory
+# Optional legacy fixed-repository mode. Leave empty to create one repo per project.
+GITEA_REPO=
+
+# Database
+# In production, provide PostgreSQL settings. They take precedence over the SQLite default.
+# Setting USE_SQLITE=false is still supported if you want to make the choice explicit.
+POSTGRES_HOST=postgres.yourserver.com
+POSTGRES_PORT=5432
+POSTGRES_USER=ai_software_factory
+POSTGRES_PASSWORD=change-me
+POSTGRES_DB=ai_software_factory
 
 # n8n
 N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
@@ -59,13 +70,19 @@ N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
 # Telegram
 TELEGRAM_BOT_TOKEN=your_telegram_bot_token
 TELEGRAM_CHAT_ID=your_chat_id
+
+# Optional: Home Assistant integration.
+# Only the base URL and token are required in the environment.
+# Entity ids, thresholds, and queue behavior can be configured from the dashboard System tab and are stored in the database.
+HOME_ASSISTANT_URL=http://homeassistant.local:8123
+HOME_ASSISTANT_TOKEN=your_home_assistant_long_lived_token
 ```
 
 ### Build and Run
 
 ```bash
 # Build Docker image
-docker build -t ai-software-factory -f Containerfile .
+DOCKER_API_VERSION=1.43 docker build -t ai-software-factory -f Containerfile .
 
 # Run with Docker Compose
 docker-compose up -d
@@ -76,26 +93,44 @@ docker-compose up -d
 1. **Send a request via Telegram:**
 
    ```
-   Name: My Awesome App
+   Build an internal task management app for our operations team.
-   Description: A web application for managing tasks
+   It should support user authentication, task CRUD, notifications, and reporting.
-   Features: user authentication, task CRUD, notifications
+   Prefer FastAPI with PostgreSQL and a simple web dashboard.
    ```
 
+   The backend now interprets free-form Telegram text with Ollama before generation.
+   If `TELEGRAM_CHAT_ID` is set, the Telegram-trigger workflow only reacts to messages from that specific chat.
+   If queueing is enabled from the dashboard System tab, Telegram prompts are stored in a durable queue and processed only when the configured Home Assistant battery and surplus thresholds are satisfied, unless you force processing via `/queue/process` or send `process_now=true`.
+
 2. **Monitor progress via Web UI:**
 
-   Open `http://yourserver:8000` to see real-time progress
+   Open `http://yourserver:8000/` to see the dashboard and `http://yourserver:8000/api` for API metadata
 
 3. **Review PRs in Gitea:**
 
    Check your gitea repository for generated PRs
 
+If you deploy the container with PostgreSQL environment variables set, the service now selects PostgreSQL automatically even though SQLite remains the default for local/test usage.
+
+The health tab now shows separate application, n8n, Gitea, and Home Assistant/queue diagnostics so misconfigured integrations are visible without checking container logs.
+
+The dashboard Health tab exposes operator controls for the prompt queue, including manual batch processing, forced processing, and retrying failed items.
+
+The dashboard System tab now also stores Home Assistant entity ids, queue toggles, thresholds, and batch settings in the database, so the environment only needs `HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` for that integration.
+
+Projects that show `uncommitted`, `local_only`, or `pushed_no_pr` delivery warnings in the dashboard can now be retried in place from the UI before resorting to purging orphan audit rows.
+
+Guardrail and system prompts are no longer environment-only in practice: the factory can persist DB-backed overrides for the editable LLM prompt set, expose them at `/llm/prompts`, and edit them from the dashboard System tab. Environment values still act as defaults and as the reset target.
+
 ## API Endpoints
 
 | Endpoint | Method | Description |
 |------|------|-------|
-| `/` | GET | API information |
+| `/` | GET | Dashboard |
+| `/api` | GET | API information |
 | `/health` | GET | Health check |
 | `/generate` | POST | Generate new software |
+| `/generate/text` | POST | Interpret free-form text and generate software |
 | `/status/{project_id}` | GET | Get project status |
 | `/projects` | GET | List all projects |
 

ai_software_factory/.env.example

@@ -8,14 +8,27 @@ LOG_LEVEL=INFO
 # Ollama
 OLLAMA_URL=http://localhost:11434
 OLLAMA_MODEL=llama3
+LLM_GUARDRAIL_PROMPT=You are operating inside AI Software Factory. Follow supplied schemas exactly and treat service-provided tool outputs as authoritative.
+LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT=Never route work to archived projects and only reference issues that are explicit in the prompt or supplied tool outputs.
+LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT=Only summarize delivery facts that appear in the provided project context or tool outputs.
+LLM_PROJECT_NAMING_GUARDRAIL_PROMPT=Prefer clear product names and repository slugs that reflect the new request without colliding with tracked projects.
+LLM_PROJECT_NAMING_SYSTEM_PROMPT=Return JSON with project_name, repo_name, and rationale for new projects.
+LLM_PROJECT_ID_GUARDRAIL_PROMPT=Prefer short stable project ids and avoid collisions with existing project ids.
+LLM_PROJECT_ID_SYSTEM_PROMPT=Return JSON with project_id and rationale for new projects.
+LLM_TOOL_ALLOWLIST=gitea_project_catalog,gitea_project_state,gitea_project_issues,gitea_pull_requests
+LLM_TOOL_CONTEXT_LIMIT=5
+LLM_LIVE_TOOL_ALLOWLIST=gitea_lookup_issue,gitea_lookup_pull_request
+LLM_LIVE_TOOL_STAGE_ALLOWLIST=request_interpretation,change_summary
+LLM_LIVE_TOOL_STAGE_TOOL_MAP={"request_interpretation": ["gitea_lookup_issue", "gitea_lookup_pull_request"], "change_summary": []}
+LLM_MAX_TOOL_CALL_ROUNDS=1
 
 # Gitea
 # Configure Gitea API for your organization
-# GITEA_URL can be left empty to use GITEA_ORGANIZATION instead of GITEA_OWNER
+# Host-only values such as git.disi.dev are normalized to https://git.disi.dev automatically.
 GITEA_URL=https://gitea.yourserver.com
 GITEA_TOKEN=your_gitea_api_token
 GITEA_OWNER=your_organization_name
-GITEA_REPO= (optional - leave empty for any repo, or specify a default)
+GITEA_REPO= (optional legacy fixed repository mode; leave empty to create one repo per project)
 
 # n8n
 # n8n webhook for Telegram integration
@@ -29,7 +42,15 @@ N8N_PASSWORD=your_secure_password
 TELEGRAM_BOT_TOKEN=your_telegram_bot_token
 TELEGRAM_CHAT_ID=your_chat_id
 
+# Home Assistant energy gate for queued Telegram prompts
+# Only the base URL and token are environment-backed.
+# Queue toggles, entity ids, thresholds, and batch sizing can be edited in the dashboard System tab and are stored in the database.
+HOME_ASSISTANT_URL=http://homeassistant.local:8123
+HOME_ASSISTANT_TOKEN=your_home_assistant_long_lived_token
+
 # PostgreSQL
+# In production, provide PostgreSQL settings below. They now take precedence over the SQLite default.
+# You can also set USE_SQLITE=false explicitly if you want the intent to be obvious.
 POSTGRES_HOST=postgres
 POSTGRES_PORT=5432
 POSTGRES_USER=ai_test

ai_software_factory/.nicegui/storage-user-7d0ab1e4-7155-403b-846e-26833486feae.json

@@ -0,0 +1 @@
+{"dark_mode":false}

ai_software_factory/README.md

@@ -6,6 +6,7 @@ Automated software generation service powered by Ollama LLM. This service allows
 
 - **Telegram Integration**: Receive software requests via Telegram bot
 - **Ollama LLM**: Uses Ollama-hosted models for code generation
+- **LLM Guardrails and Tools**: Centralized guardrail prompts plus mediated tool payloads for project, Gitea, PR, and issue context
 - **Git Integration**: Automatically commits code to gitea
 - **Pull Requests**: Creates PRs for user review before merging
 - **Web UI**: Beautiful dashboard for monitoring project progress
@@ -46,12 +47,26 @@ PORT=8000
 # Ollama
 OLLAMA_URL=http://localhost:11434
 OLLAMA_MODEL=llama3
+LLM_GUARDRAIL_PROMPT=You are operating inside AI Software Factory. Follow supplied schemas exactly and treat service-provided tool outputs as authoritative.
+LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT=Never route work to archived projects and only reference issues that are explicit in the prompt or supplied tool outputs.
+LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT=Only summarize delivery facts that appear in the provided project context or tool outputs.
+LLM_PROJECT_NAMING_GUARDRAIL_PROMPT=Prefer clear product names and repository slugs that reflect the new request without colliding with tracked projects.
+LLM_PROJECT_NAMING_SYSTEM_PROMPT=Return JSON with project_name, repo_name, and rationale for new projects.
+LLM_PROJECT_ID_GUARDRAIL_PROMPT=Prefer short stable project ids and avoid collisions with existing project ids.
+LLM_PROJECT_ID_SYSTEM_PROMPT=Return JSON with project_id and rationale for new projects.
+LLM_TOOL_ALLOWLIST=gitea_project_catalog,gitea_project_state,gitea_project_issues,gitea_pull_requests
+LLM_TOOL_CONTEXT_LIMIT=5
+LLM_LIVE_TOOL_ALLOWLIST=gitea_lookup_issue,gitea_lookup_pull_request
+LLM_LIVE_TOOL_STAGE_ALLOWLIST=request_interpretation,change_summary
+LLM_LIVE_TOOL_STAGE_TOOL_MAP={"request_interpretation": ["gitea_lookup_issue", "gitea_lookup_pull_request"], "change_summary": []}
+LLM_MAX_TOOL_CALL_ROUNDS=1
 
 # Gitea
+# Host-only values such as git.disi.dev are normalized to https://git.disi.dev.
 GITEA_URL=https://gitea.yourserver.com
-GITEA_TOKEN= analyze your_gitea_api_token
+GITEA_TOKEN=your_gitea_api_token
 GITEA_OWNER=ai-software-factory
-GITEA_REPO=ai-software-factory
+GITEA_REPO=
 
 # n8n
 N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
@@ -59,6 +74,12 @@ N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
 # Telegram
 TELEGRAM_BOT_TOKEN=your_telegram_bot_token
 TELEGRAM_CHAT_ID=your_chat_id
+
+# Optional: Home Assistant integration.
+# Only the base URL and token are required in the environment.
+# Entity ids, thresholds, and queue behavior can be configured from the dashboard System tab and are stored in the database.
+HOME_ASSISTANT_URL=http://homeassistant.local:8123
+HOME_ASSISTANT_TOKEN=your_home_assistant_long_lived_token
 ```
 
 ### Build and Run
@@ -81,6 +102,10 @@ docker-compose up -d
    Features: user authentication, task CRUD, notifications
    ```
 
+   If queueing is enabled from the dashboard System tab, Telegram prompts are queued durably and processed only when Home Assistant reports the configured battery and surplus thresholds. Operators can override the gate via `/queue/process` or by sending `process_now=true` to `/generate/text`.
+
+The dashboard System tab stores Home Assistant entity ids, queue toggles, thresholds, and batch settings in the database, so the environment only needs `HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` for that integration.
+
 2. **Monitor progress via Web UI:**
 
    Open `http://yourserver:8000` to see real-time progress
@@ -99,6 +124,39 @@ docker-compose up -d
 | `/status/{project_id}` | GET | Get project status |
 | `/projects` | GET | List all projects |
 
+## LLM Guardrails and Tool Access
+
+External LLM calls are now routed through a centralized client that applies:
+
+- A global guardrail prompt for every outbound model request
+- Stage-specific guardrails for request interpretation and change summaries
+- Service-mediated tool outputs that expose tracked Gitea/project state without giving the model raw credentials
+
+Current mediated tools include:
+
+- `gitea_project_catalog`: active tracked projects and repository mappings
+- `gitea_project_state`: current repository, PR, and linked-issue state for the project in scope
+- `gitea_project_issues`: tracked open issues for the relevant repository
+- `gitea_pull_requests`: tracked pull requests for the relevant repository
+
+The service also supports a bounded live tool-call loop for selected lookups. When enabled, the model may request one live call such as `gitea_lookup_issue` or `gitea_lookup_pull_request`, the service executes it against Gitea, and the final model response is generated from the returned result. This remains mediated by the service, so the model never receives raw credentials.
+
+Live tool access is stage-aware. `LLM_LIVE_TOOL_ALLOWLIST` controls which live tools exist globally, while `LLM_LIVE_TOOL_STAGE_ALLOWLIST` controls which LLM stages may use them. If you need per-stage subsets, `LLM_LIVE_TOOL_STAGE_TOOL_MAP` accepts a JSON object mapping each stage to the exact tools it may use. For example, you can allow issue and PR lookups during `request_interpretation` while keeping `change_summary` fully read-only.
+
+When the interpreter decides a prompt starts a new project, the service can run a dedicated `project_naming` LLM stage before generation. `LLM_PROJECT_NAMING_SYSTEM_PROMPT` and `LLM_PROJECT_NAMING_GUARDRAIL_PROMPT` let you steer how project titles and repository slugs are chosen. The interpreter now checks tracked project repositories plus live Gitea repository names when available, so if the model suggests a colliding repo slug the service will automatically move to the next available slug.
+
+New project creation can also run a dedicated `project_id_naming` stage. `LLM_PROJECT_ID_SYSTEM_PROMPT` and `LLM_PROJECT_ID_GUARDRAIL_PROMPT` control how stable project ids are chosen, and the service will append deterministic numeric suffixes when an id is already taken instead of always falling back to a random UUID-based id.
+
+Runtime visibility for the active guardrails, mediated tools, live tools, and model configuration is available at `/llm/runtime` and in the dashboard System tab.
+
+Operational visibility for the Gitea integration, Home Assistant energy gate, and queued prompt counts is available in the dashboard Health tab, plus `/gitea/health`, `/home-assistant/health`, and `/queue`.
+
+The dashboard Health tab also includes operator controls for manually processing queued Telegram prompts, force-processing them when needed, and retrying failed items.
+
+Editable guardrail and system prompts are persisted in the database as overrides on top of the environment defaults. The current merged values are available at `/llm/prompts`, and the dashboard System tab can edit or reset them without restarting the service.
+
+These tool payloads are appended to the model prompt as authoritative JSON generated by the service, so the LLM can reason over live project and Gitea context while remaining constrained by the configured guardrails.
+
 ## Development
 
 ### Makefile Targets

ai_software_factory/VERSION

@@ -1 +1 @@
-0.3.3
+0.9.4

ai_software_factory/agents/__init__.py

@@ -1,11 +1,11 @@
 """AI Software Factory agents."""
 
-from agents.orchestrator import AgentOrchestrator
+from .orchestrator import AgentOrchestrator
-from agents.git_manager import GitManager
+from .git_manager import GitManager
-from agents.ui_manager import UIManager
+from .ui_manager import UIManager
-from agents.telegram import TelegramHandler
+from .telegram import TelegramHandler
-from agents.gitea import GiteaAPI
+from .gitea import GiteaAPI
-from agents.database_manager import DatabaseManager
+from .database_manager import DatabaseManager
 
 __all__ = [
     "AgentOrchestrator",

ai_software_factory/agents/change_summary.py

@@ -0,0 +1,125 @@
+"""Generate concise chat-friendly summaries of software generation results."""
+
+from __future__ import annotations
+
+try:
+    from ..config import settings
+    from .llm_service import LLMServiceClient
+except ImportError:
+    from config import settings
+    from agents.llm_service import LLMServiceClient
+
+
+class ChangeSummaryGenerator:
+    """Create a readable overview of generated changes for chat responses."""
+
+    def __init__(self, ollama_url: str | None = None, model: str | None = None):
+        self.ollama_url = (ollama_url or settings.ollama_url).rstrip('/')
+        self.model = model or settings.OLLAMA_MODEL
+        self.llm_client = LLMServiceClient(ollama_url=self.ollama_url, model=self.model)
+
+    async def summarize(self, context: dict) -> str:
+        """Summarize project changes with Ollama, or fall back to a deterministic overview."""
+        summary, _trace = await self.summarize_with_trace(context)
+        return summary
+
+    async def summarize_with_trace(self, context: dict) -> tuple[str, dict]:
+        """Summarize project changes with Ollama, or fall back to a deterministic overview."""
+        prompt = self._prompt(context)
+        system_prompt = (
+            'You write concise but informative mobile chat summaries of software delivery work. '
+            'Write 3 to 5 sentences. Mention the application goal, main delivered pieces, '
+            'technical direction, and what the user should expect next. Avoid markdown bullets.'
+        )
+        content, trace = await self.llm_client.chat_with_trace(
+            stage='change_summary',
+            system_prompt=system_prompt,
+            user_prompt=prompt,
+            tool_context_input={
+                'project_id': context.get('project_id'),
+                'project_name': context.get('name'),
+                'repository': context.get('repository'),
+                'repository_url': context.get('repository_url'),
+                'pull_request': context.get('pull_request'),
+                'pull_request_url': context.get('pull_request_url'),
+                'pull_request_state': context.get('pull_request_state'),
+                'related_issue': context.get('related_issue'),
+                'issues': [context.get('related_issue')] if context.get('related_issue') else [],
+            },
+        )
+        if content:
+            return content.strip(), trace
+
+        fallback = self._fallback(context)
+        return fallback, {
+            'stage': 'change_summary',
+            'provider': 'fallback',
+            'model': self.model,
+            'system_prompt': system_prompt,
+            'user_prompt': prompt,
+            'assistant_response': fallback,
+            'raw_response': {'fallback': 'deterministic', 'llm_trace': trace.get('raw_response') if isinstance(trace, dict) else None},
+            'guardrails': trace.get('guardrails') if isinstance(trace, dict) else [],
+            'tool_context': trace.get('tool_context') if isinstance(trace, dict) else [],
+            'fallback_used': True,
+        }
+
+    def _prompt(self, context: dict) -> str:
+        features = ', '.join(context.get('features') or []) or 'No explicit features recorded'
+        tech_stack = ', '.join(context.get('tech_stack') or []) or 'No explicit tech stack recorded'
+        changed_files = ', '.join(context.get('changed_files') or []) or 'No files recorded'
+        logs = ' | '.join((context.get('logs') or [])[:4]) or 'No log excerpts'
+        return (
+            f"Project name: {context.get('name', 'Unknown project')}\n"
+            f"Description: {context.get('description', '')}\n"
+            f"Features: {features}\n"
+            f"Tech stack: {tech_stack}\n"
+            f"Changed files: {changed_files}\n"
+            f"Repository: {context.get('repository_url') or 'No repository URL'}\n"
+            f"Pull request: {context.get('pull_request_url') or 'No pull request URL'}\n"
+            f"Pull request state: {context.get('pull_request_state') or 'No pull request state'}\n"
+            f"Status message: {context.get('message') or ''}\n"
+            f"Log excerpts: {logs}\n"
+            "Write a broad but phone-friendly summary of what was done."
+        )
+
+    def _fallback(self, context: dict) -> str:
+        name = context.get('name', 'The project')
+        description = context.get('description') or 'a software request'
+        changed_files = context.get('changed_files') or []
+        features = context.get('features') or []
+        tech_stack = context.get('tech_stack') or []
+        repo_url = context.get('repository_url')
+        repo_status = context.get('repository_status')
+        pr_url = context.get('pull_request_url')
+        pr_state = context.get('pull_request_state')
+
+        first_sentence = f"{name} was generated from your request for {description}."
+        feature_sentence = (
+            f"The delivery focused on {', '.join(features[:3])}."
+            if features else
+            "The delivery focused on turning the request into an initial runnable application skeleton."
+        )
+        tech_sentence = (
+            f"The generated implementation currently targets {', '.join(tech_stack[:3])}."
+            if tech_stack else
+            "The implementation was created with the current default stack configured for the factory."
+        )
+        file_sentence = (
+            f"Key artifacts were updated across {len(changed_files)} files, including {', '.join(changed_files[:3])}."
+            if changed_files else
+            "The service completed the generation flow, but no changed file list was returned."
+        )
+        if repo_url:
+            repo_sentence = f"The resulting project is tracked at {repo_url}."
+        elif repo_status in {'pending', 'skipped', 'error'}:
+            repo_sentence = "Repository provisioning was not confirmed, so review the Gitea status in the dashboard before assuming a remote repo exists."
+        else:
+            repo_sentence = "The project is ready for further review in the dashboard."
+        if pr_url and pr_state == 'open':
+            pr_sentence = f"An open pull request is ready for review at {pr_url}, and later prompts will continue updating that same PR until it is merged."
+        elif pr_url:
+            pr_sentence = f"The latest pull request is available at {pr_url}."
+        else:
+            pr_sentence = "No pull request link was recorded for this delivery."
+        return ' '.join([first_sentence, feature_sentence, tech_sentence, file_sentence, repo_sentence, pr_sentence])

ai_software_factory/agents/git_manager.py

@@ -1,52 +1,155 @@
 """Git manager for project operations."""
 
 import os
+import shutil
 import subprocess
+import tempfile
+from pathlib import Path
 from typing import Optional
 
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
 
 class GitManager:
     """Manages git operations for the project."""
     
-    def __init__(self, project_id: str):
+    def __init__(self, project_id: str, project_dir: str | None = None):
         if not project_id:
             raise ValueError("project_id cannot be empty or None")
         self.project_id = project_id
-        self.project_dir = f"{os.path.dirname(__file__)}/../../test-project/{project_id}"
+        if project_dir:
+            resolved = Path(project_dir).expanduser().resolve()
+        else:
+            project_path = Path(project_id)
+            if project_path.is_absolute() or len(project_path.parts) > 1:
+                resolved = project_path.expanduser().resolve()
+            else:
+                base_root = settings.projects_root
+                if base_root.name != "test-project":
+                    base_root = base_root / "test-project"
+                resolved = (base_root / project_id).resolve()
+        self.project_dir = str(resolved)
+
+    def is_git_available(self) -> bool:
+        """Return whether the git executable is available in the current environment."""
+        return shutil.which('git') is not None
+
+    def _ensure_git_available(self) -> None:
+        """Raise a clear error when git is not installed in the runtime environment."""
+        if not self.is_git_available():
+            raise RuntimeError('git executable is not available in PATH')
+
+    def _run(self, args: list[str], env: dict | None = None, check: bool = True) -> subprocess.CompletedProcess:
+        """Run a git command in the project directory."""
+        self._ensure_git_available()
+        return subprocess.run(
+            args,
+            check=check,
+            capture_output=True,
+            text=True,
+            cwd=self.project_dir,
+            env=env,
+        )
+
+    def has_repo(self) -> bool:
+        """Return whether the project directory already contains a git repository."""
+        return Path(self.project_dir, '.git').exists()
     
     def init_repo(self):
         """Initialize git repository."""
         os.makedirs(self.project_dir, exist_ok=True)
-        os.chdir(self.project_dir)
+        self._run(["git", "init", "-b", "main"])
-        subprocess.run(["git", "init"], check=True, capture_output=True)
+        self._run(["git", "config", "user.name", "AI Software Factory"])
+        self._run(["git", "config", "user.email", "factory@local.invalid"])
     
     def add_files(self, paths: list[str]):
         """Add files to git staging."""
-        subprocess.run(["git", "add"] + paths, check=True, capture_output=True)
+        self._run(["git", "add"] + paths)
 
-    def commit(self, message: str):
+    def checkout_branch(self, branch_name: str, create: bool = False, start_point: str | None = None) -> None:
+        """Switch to a branch, optionally creating it from a start point."""
+        if create:
+            args = ["git", "checkout", "-B", branch_name]
+            if start_point:
+                args.append(start_point)
+            self._run(args)
+            return
+        self._run(["git", "checkout", branch_name])
+
+    def branch_exists(self, branch_name: str) -> bool:
+        """Return whether a local branch exists."""
+        result = self._run(["git", "show-ref", "--verify", f"refs/heads/{branch_name}"], check=False)
+        return result.returncode == 0
+    
+    def commit(self, message: str) -> str:
         """Create a git commit."""
-        subprocess.run(
+        self._run(["git", "commit", "-m", message])
-            ["git", "commit", "-m", message],
+        return self.current_head()
-            check=True,
+
-            capture_output=True
+    def create_empty_commit(self, message: str) -> str:
-        )
+        """Create an empty commit."""
+        self._run(["git", "commit", "--allow-empty", "-m", message])
+        return self.current_head()
     
     def push(self, remote: str = "origin", branch: str = "main"):
         """Push changes to remote."""
-        subprocess.run(
+        self._run(["git", "push", "-u", remote, branch])
-            ["git", "push", "-u", remote, branch],
+
-            check=True,
+    def ensure_remote(self, remote: str, url: str) -> None:
-            capture_output=True
+        """Create or update a remote URL."""
+        result = self._run(["git", "remote", "get-url", remote], check=False)
+        if result.returncode == 0:
+            self._run(["git", "remote", "set-url", remote, url])
+        else:
+            self._run(["git", "remote", "add", remote, url])
+
+    def push_with_credentials(
+        self,
+        remote_url: str,
+        username: str,
+        password: str,
+        remote: str = "origin",
+        branch: str = "main",
+    ) -> None:
+        """Push to a remote over HTTPS using an askpass helper."""
+        os.makedirs(self.project_dir, exist_ok=True)
+        self.ensure_remote(remote, remote_url)
+        helper_contents = "#!/bin/sh\ncase \"$1\" in\n  *Username*) printf '%s\\n' \"$GIT_ASKPASS_USERNAME\" ;;\n  *) printf '%s\\n' \"$GIT_ASKPASS_PASSWORD\" ;;\nesac\n"
+        helper_path: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile('w', delete=False, dir=self.project_dir, prefix='git-askpass-', suffix='.sh') as helper_file:
+                helper_file.write(helper_contents)
+                helper_path = helper_file.name
+            os.chmod(helper_path, 0o700)
+            env = os.environ.copy()
+            env.update(
+                {
+                    "GIT_TERMINAL_PROMPT": "0",
+                    "GIT_ASKPASS": helper_path,
+                    "GIT_ASKPASS_USERNAME": username,
+                    "GIT_ASKPASS_PASSWORD": password,
+                }
             )
+            self._run(["git", "push", "-u", remote, branch], env=env)
+        finally:
+            if helper_path:
+                Path(helper_path).unlink(missing_ok=True)
     
     def create_branch(self, branch_name: str):
         """Create and switch to a new branch."""
-        subprocess.run(
+        self._run(["git", "checkout", "-b", branch_name])
-            ["git", "checkout", "-b", branch_name],
+
-            check=True,
+    def revert_commit(self, commit_hash: str, no_edit: bool = True) -> str:
-            capture_output=True
+        """Revert a commit and return the new HEAD."""
-        )
+        args = ["git", "revert"]
+        if no_edit:
+            args.append("--no-edit")
+        args.append(commit_hash)
+        self._run(args)
+        return self.current_head()
     
     def create_pr(
         self,
@@ -70,6 +173,18 @@ class GitManager:
         result = subprocess.run(
             ["git", "status", "--porcelain"],
             capture_output=True,
-            text=True
+            text=True,
+            cwd=self.project_dir,
         )
         return result.stdout.strip()
+
+    def current_head(self) -> str:
+        """Return the current commit hash."""
+        return self._run(["git", "rev-parse", "HEAD"]).stdout.strip()
+
+    def current_head_or_none(self) -> str | None:
+        """Return the current commit hash when the repository already has commits."""
+        result = self._run(["git", "rev-parse", "HEAD"], check=False)
+        if result.returncode != 0:
+            return None
+        return result.stdout.strip() or None

ai_software_factory/agents/gitea.py

@@ -1,7 +1,23 @@
-"""Gitea API integration for commits and PRs."""
+"""Gitea API integration for repository and pull request operations."""
 
 import os
-from typing import Optional
+import urllib.error
+import urllib.request
+import json
+from urllib.parse import urlparse
+
+
+def _normalize_base_url(base_url: str) -> str:
+    """Normalize host-only service addresses into valid absolute URLs."""
+    normalized = (base_url or '').strip().rstrip('/')
+    if not normalized:
+        return ''
+    if '://' not in normalized:
+        normalized = f'https://{normalized}'
+    parsed = urlparse(normalized)
+    if not parsed.scheme or not parsed.netloc:
+        return ''
+    return normalized
 
 
 class GiteaAPI:
@@ -9,12 +25,12 @@ class GiteaAPI:
 
     def __init__(self, token: str, base_url: str, owner: str | None = None, repo: str | None = None):
         self.token = token
-        self.base_url = base_url.rstrip("/")
+        self.base_url = _normalize_base_url(base_url)
         self.owner = owner
         self.repo = repo
         self.headers = {
             "Authorization": f"token {token}",
-            "Content-Type": "application/json"
+            "Content-Type": "application/json",
         }
 
     def get_config(self) -> dict:
@@ -23,60 +39,177 @@ class GiteaAPI:
         token = os.getenv("GITEA_TOKEN", "")
         owner = os.getenv("GITEA_OWNER", "ai-test")
         repo = os.getenv("GITEA_REPO", "")
-        
-        # Allow empty repo for any repo mode (org/repo pattern)
-        if not repo:
-            repo = "any-repo"  # Use this as a placeholder for org/repo operations
-        
-        # Check for repo suffix pattern (e.g., repo-* for multiple repos)
-        repo_suffix = os.getenv("GITEA_REPO_SUFFIX", "")
-        
         return {
-            "base_url": base_url.rstrip("/"),
+            "base_url": _normalize_base_url(base_url),
             "token": token,
             "owner": owner,
             "repo": repo,
-            "repo_suffix": repo_suffix,
+            "supports_project_repos": not bool(repo),
-            "supports_any_repo": not repo or repo_suffix
         }
 
     def get_auth_headers(self) -> dict:
         """Get authentication headers."""
         return {
             "Authorization": f"token {self.token}",
-            "Content-Type": "application/json"
+            "Content-Type": "application/json",
         }
 
-    async def create_branch(self, branch: str, base: str = "main", owner: str | None = None, repo: str | None = None):
+    def _api_url(self, path: str) -> str:
-        """Create a new branch.
+        """Build a Gitea API URL from a relative path."""
+        return f"{self.base_url}/api/v1/{path.lstrip('/')}"
 
-        Args:
+    def build_repo_git_url(self, owner: str | None = None, repo: str | None = None) -> str | None:
-            branch: Branch name to create
+        """Build the clone URL for a repository."""
-            base: Base branch to create from (default: "main")
-            owner: Organization/owner name (optional, falls back to configured owner)
-            repo: Repository name (optional, falls back to configured repo)
-            
-        Returns:
-            API response or error message
-        """
-        # Use provided owner/repo or fall back to configured values
         _owner = owner or self.owner
         _repo = repo or self.repo
+        if not _owner or not _repo:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}.git"
 
-        url = f"{self.base_url}/repos/{_owner}/{_repo}/branches/{branch}"
+    def build_commit_url(self, commit_hash: str, owner: str | None = None, repo: str | None = None) -> str | None:
-        payload = {"base": base}
+        """Build a browser URL for a commit."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo or not commit_hash:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}/commit/{commit_hash}"
 
+    def build_compare_url(self, base_ref: str, head_ref: str, owner: str | None = None, repo: str | None = None) -> str | None:
+        """Build a browser URL for a compare view."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo or not base_ref or not head_ref:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}/compare/{base_ref}...{head_ref}"
+
+    def build_pull_request_url(self, pr_number: int, owner: str | None = None, repo: str | None = None) -> str | None:
+        """Build a browser URL for a pull request."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo or not pr_number:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}/pulls/{pr_number}"
+
+    async def _request(self, method: str, path: str, payload: dict | None = None) -> dict:
+        """Perform a Gitea API request and normalize the response."""
         try:
             import aiohttp
+
             async with aiohttp.ClientSession() as session:
-                async with session.post(url, headers=self.get_auth_headers(), json=payload) as resp:
+                async with session.request(
-                    if resp.status == 201:
+                    method,
+                    self._api_url(path),
+                    headers=self.get_auth_headers(),
+                    json=payload,
+                ) as resp:
+                    if resp.status in (200, 201):
                         return await resp.json()
-                    else:
+                    return {"error": await resp.text(), "status_code": resp.status}
-                        return {"error": await resp.text()}
         except Exception as e:
             return {"error": str(e)}
 
+    def _request_sync(self, method: str, path: str, payload: dict | None = None) -> dict:
+        """Perform a synchronous Gitea API request."""
+        try:
+            if not self.base_url:
+                return {'error': 'Gitea base URL is not configured or is invalid'}
+            request = urllib.request.Request(
+                self._api_url(path),
+                headers=self.get_auth_headers(),
+                method=method.upper(),
+            )
+            if payload is not None:
+                request.data = json.dumps(payload).encode('utf-8')
+            with urllib.request.urlopen(request) as response:
+                body = response.read().decode('utf-8')
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as exc:
+            try:
+                body = exc.read().decode('utf-8')
+            except Exception:
+                body = str(exc)
+            return {'error': body, 'status_code': exc.code}
+        except Exception as exc:
+            return {'error': str(exc)}
+
+    def build_project_repo_name(self, project_id: str, project_name: str | None = None) -> str:
+        """Build a repository name for a generated project."""
+        preferred = (project_name or project_id or "project").strip().lower().replace(" ", "-")
+        sanitized = "".join(ch if ch.isalnum() or ch in {"-", "_"} else "-" for ch in preferred)
+        while "--" in sanitized:
+            sanitized = sanitized.replace("--", "-")
+        return sanitized.strip("-") or project_id
+
+    async def create_repo(
+        self,
+        repo_name: str,
+        owner: str | None = None,
+        description: str | None = None,
+        private: bool = False,
+        auto_init: bool = True,
+    ) -> dict:
+        """Create a repository inside the configured organization."""
+        _owner = owner or self.owner
+        if not _owner:
+            return {"error": "Owner or organization is required"}
+
+        payload = {
+            "name": repo_name,
+            "description": description or f"AI-generated project repository for {repo_name}",
+            "private": private,
+            "auto_init": auto_init,
+            "default_branch": "main",
+        }
+        result = await self._request("POST", f"orgs/{_owner}/repos", payload)
+        if result.get("status_code") == 409:
+            existing = await self.get_repo_info(owner=_owner, repo=repo_name)
+            if not existing.get("error"):
+                existing["status"] = "exists"
+                return existing
+        if not result.get("error"):
+            result.setdefault("status", "created")
+        return result
+
+    async def delete_repo(self, owner: str | None = None, repo: str | None = None) -> dict:
+        """Delete a repository from the configured organization/user."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo:
+            return {'error': 'Owner and repository name are required'}
+        result = await self._request('DELETE', f'repos/{_owner}/{_repo}')
+        if not result.get('error'):
+            result.setdefault('status', 'deleted')
+        return result
+
+    def delete_repo_sync(self, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously delete a repository from the configured organization/user."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo:
+            return {'error': 'Owner and repository name are required'}
+        result = self._request_sync('DELETE', f'repos/{_owner}/{_repo}')
+        if not result.get('error'):
+            result.setdefault('status', 'deleted')
+        return result
+
+    async def get_current_user(self) -> dict:
+        """Get the user associated with the configured token."""
+        return await self._request("GET", "user")
+
+    def get_current_user_sync(self) -> dict:
+        """Synchronously get the user associated with the configured token."""
+        return self._request_sync("GET", "user")
+
+    async def create_branch(self, branch: str, base: str = "main", owner: str | None = None, repo: str | None = None):
+        """Create a new branch."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request(
+            "POST",
+            f"repos/{_owner}/{_repo}/branches",
+            {"new_branch_name": branch, "old_ref_name": base},
+        )
+
     async def create_pull_request(
         self,
         title: str,
@@ -84,43 +217,176 @@ class GiteaAPI:
         owner: str,
         repo: str,
         base: str = "main",
-        head: str | None = None
+        head: str | None = None,
     ) -> dict:
-        """Create a pull request.
+        """Create a pull request."""
-        
-        Args:
-            title: PR title
-            body: PR description
-            owner: Organization/owner name
-            repo: Repository name
-            base: Base branch (default: "main")
-            head: Head branch (optional, auto-generated if not provided)
-            
-        Returns:
-            API response or error message
-        """
         _owner = owner or self.owner
         _repo = repo or self.repo
-        
-        url = f"{self.base_url}/repos/{_owner}/{_repo}/pulls"
-        
         payload = {
             "title": title,
             "body": body,
-            "base": {"branch": base},
+            "base": base,
-            "head": head or f"{_owner}-{_repo}-ai-gen-{hash(title) % 10000}"
+            "head": head or f"{_owner}-{_repo}-ai-gen-{hash(title) % 10000}",
         }
+        return await self._request("POST", f"repos/{_owner}/{_repo}/pulls", payload)
 
-        try:
+    def create_pull_request_sync(
-            import aiohttp
+        self,
-            async with aiohttp.ClientSession() as session:
+        title: str,
-                async with session.post(url, headers=self.get_auth_headers(), json=payload) as resp:
+        body: str,
-                    if resp.status == 201:
+        owner: str,
-                        return await resp.json()
+        repo: str,
-                    else:
+        base: str = "main",
-                        return {"error": await resp.text()}
+        head: str | None = None,
-        except Exception as e:
+    ) -> dict:
-            return {"error": str(e)}
+        """Synchronously create a pull request."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        payload = {
+            "title": title,
+            "body": body,
+            "base": base,
+            "head": head or f"{_owner}-{_repo}-ai-gen-{hash(title) % 10000}",
+        }
+        return self._request_sync("POST", f"repos/{_owner}/{_repo}/pulls", payload)
+
+    async def list_pull_requests(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """List pull requests for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/pulls?state={state}")
+
+    def list_pull_requests_sync(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """Synchronously list pull requests for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/pulls?state={state}")
+
+    async def list_repositories(self, owner: str | None = None) -> dict | list:
+        """List repositories within the configured organization."""
+        _owner = owner or self.owner
+        return await self._request("GET", f"orgs/{_owner}/repos")
+
+    def list_repositories_sync(self, owner: str | None = None) -> dict | list:
+        """Synchronously list repositories within the configured organization."""
+        _owner = owner or self.owner
+        return self._request_sync("GET", f"orgs/{_owner}/repos")
+
+    async def list_branches(self, owner: str | None = None, repo: str | None = None) -> dict | list:
+        """List repository branches."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/branches")
+
+    def list_branches_sync(self, owner: str | None = None, repo: str | None = None) -> dict | list:
+        """Synchronously list repository branches."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/branches")
+
+    async def list_issues(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """List repository issues, excluding pull requests at the consumer layer."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/issues?state={state}")
+
+    def list_issues_sync(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """Synchronously list repository issues."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/issues?state={state}")
+
+    async def get_issue(self, issue_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Return one repository issue by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/issues/{issue_number}")
+
+    def get_issue_sync(self, issue_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously return one repository issue by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/issues/{issue_number}")
+
+    async def list_repo_commits(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        limit: int = 25,
+        branch: str | None = None,
+    ) -> dict | list:
+        """List recent commits for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        branch_query = f"&sha={branch}" if branch else ""
+        return await self._request("GET", f"repos/{_owner}/{_repo}/commits?limit={limit}{branch_query}")
+
+    def list_repo_commits_sync(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        limit: int = 25,
+        branch: str | None = None,
+    ) -> dict | list:
+        """Synchronously list recent commits for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        branch_query = f"&sha={branch}" if branch else ""
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/commits?limit={limit}{branch_query}")
+
+    async def get_commit(
+        self,
+        commit_hash: str,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> dict:
+        """Return one commit by hash."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/git/commits/{commit_hash}")
+
+    def get_commit_sync(
+        self,
+        commit_hash: str,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> dict:
+        """Synchronously return one commit by hash."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/git/commits/{commit_hash}")
+
+    async def get_pull_request(self, pr_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Return one pull request by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/pulls/{pr_number}")
+
+    def get_pull_request_sync(self, pr_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously return one pull request by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/pulls/{pr_number}")
 
     async def push_commit(
         self,
@@ -128,25 +394,13 @@ class GiteaAPI:
         files: list[dict],
         message: str,
         owner: str | None = None,
-        repo: str | None = None
+        repo: str | None = None,
     ) -> dict:
-        """
+        """Push files to a branch.
-        Push files to a branch.
 
         In production, this would use gitea's API or git push.
-        For now, we'll simulate the operation.
+        For now, this remains simulated.
-        
-        Args:
-            branch: Branch name
-            files: List of files to push
-            message: Commit message
-            owner: Organization/owner name (optional, falls back to configured owner)
-            repo: Repository name (optional, falls back to configured repo)
-            
-        Returns:
-            Status response
         """
-        # Use provided owner/repo or fall back to configured values
         _owner = owner or self.owner
         _repo = repo or self.repo
 
@@ -156,35 +410,25 @@ class GiteaAPI:
             "message": message,
             "files": files,
             "owner": _owner,
-            "repo": _repo
+            "repo": _repo,
         }
 
     async def get_repo_info(self, owner: str | None = None, repo: str | None = None) -> dict:
-        """Get repository information.
+        """Get repository information."""
-        
-        Args:
-            owner: Organization/owner name (optional, falls back to configured owner)
-            repo: Repository name (optional, falls back to configured repo)
-            
-        Returns:
-            Repository info or error message
-        """
-        # Use provided owner/repo or fall back to configured values
         _owner = owner or self.owner
         _repo = repo or self.repo
 
         if not _repo:
             return {"error": "Repository name required for org operations"}
 
-        url = f"{self.base_url}/repos/{_owner}/{_repo}"
+        return await self._request("GET", f"repos/{_owner}/{_repo}")
 
-        try:
+    def get_repo_info_sync(self, owner: str | None = None, repo: str | None = None) -> dict:
-            import aiohttp
+        """Synchronously get repository information."""
-            async with aiohttp.ClientSession() as session:
+        _owner = owner or self.owner
-                async with session.get(url, headers=self.get_auth_headers()) as resp:
+        _repo = repo or self.repo
-                    if resp.status == 200:
+
-                        return await resp.json()
+        if not _repo:
-                    else:
+            return {"error": "Repository name required for org operations"}
-                        return {"error": await resp.text()}
+
-        except Exception as e:
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}")
-            return {"error": str(e)}

ai_software_factory/agents/home_assistant.py

@@ -0,0 +1,162 @@
+"""Home Assistant integration for energy-gated queue processing."""
+
+from __future__ import annotations
+
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
+
+class HomeAssistantAgent:
+    """Query Home Assistant for queue-processing eligibility and health."""
+
+    def __init__(self, base_url: str | None = None, token: str | None = None):
+        self.base_url = (base_url or settings.home_assistant_url).rstrip('/')
+        self.token = token or settings.home_assistant_token
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            'Authorization': f'Bearer {self.token}',
+            'Content-Type': 'application/json',
+        }
+
+    def _state_url(self, entity_id: str) -> str:
+        return f'{self.base_url}/api/states/{entity_id}'
+
+    async def _get_state(self, entity_id: str) -> dict:
+        if not self.base_url:
+            return {'error': 'Home Assistant URL is not configured'}
+        if not self.token:
+            return {'error': 'Home Assistant token is not configured'}
+        if not entity_id:
+            return {'error': 'Home Assistant entity id is not configured'}
+        try:
+            import aiohttp
+
+            async with aiohttp.ClientSession() as session:
+                async with session.get(self._state_url(entity_id), headers=self._headers()) as resp:
+                    payload = await resp.json(content_type=None)
+                    if 200 <= resp.status < 300:
+                        return payload if isinstance(payload, dict) else {'value': payload}
+                    return {'error': payload, 'status_code': resp.status}
+        except Exception as exc:
+            return {'error': str(exc)}
+
+    def _get_state_sync(self, entity_id: str) -> dict:
+        if not self.base_url:
+            return {'error': 'Home Assistant URL is not configured'}
+        if not self.token:
+            return {'error': 'Home Assistant token is not configured'}
+        if not entity_id:
+            return {'error': 'Home Assistant entity id is not configured'}
+        try:
+            import json
+            import urllib.error
+            import urllib.request
+
+            request = urllib.request.Request(self._state_url(entity_id), headers=self._headers(), method='GET')
+            with urllib.request.urlopen(request) as response:
+                body = response.read().decode('utf-8')
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as exc:
+            try:
+                body = exc.read().decode('utf-8')
+            except Exception:
+                body = str(exc)
+            return {'error': body, 'status_code': exc.code}
+        except Exception as exc:
+            return {'error': str(exc)}
+
+    @staticmethod
+    def _coerce_float(payload: dict) -> float | None:
+        raw = payload.get('state') if isinstance(payload, dict) else None
+        try:
+            return float(raw)
+        except Exception:
+            return None
+
+    async def queue_gate_status(self, force: bool = False) -> dict:
+        """Return whether queued prompts may be processed now."""
+        if force or settings.prompt_queue_force_process:
+            return {
+                'status': 'success',
+                'allowed': True,
+                'forced': True,
+                'reason': 'Queue override is enabled',
+            }
+        battery = await self._get_state(settings.home_assistant_battery_entity_id)
+        surplus = await self._get_state(settings.home_assistant_surplus_entity_id)
+        battery_value = self._coerce_float(battery)
+        surplus_value = self._coerce_float(surplus)
+        checks = []
+        if battery.get('error'):
+            checks.append({'name': 'battery', 'ok': False, 'message': str(battery.get('error')), 'entity_id': settings.home_assistant_battery_entity_id})
+        else:
+            checks.append({'name': 'battery', 'ok': battery_value is not None and battery_value >= settings.home_assistant_battery_full_threshold, 'message': f'{battery_value}%', 'entity_id': settings.home_assistant_battery_entity_id})
+        if surplus.get('error'):
+            checks.append({'name': 'surplus', 'ok': False, 'message': str(surplus.get('error')), 'entity_id': settings.home_assistant_surplus_entity_id})
+        else:
+            checks.append({'name': 'surplus', 'ok': surplus_value is not None and surplus_value >= settings.home_assistant_surplus_threshold_watts, 'message': f'{surplus_value} W', 'entity_id': settings.home_assistant_surplus_entity_id})
+        allowed = all(check['ok'] for check in checks)
+        return {
+            'status': 'success' if allowed else 'blocked',
+            'allowed': allowed,
+            'forced': False,
+            'checks': checks,
+            'battery_level': battery_value,
+            'surplus_watts': surplus_value,
+            'thresholds': {
+                'battery_full_percent': settings.home_assistant_battery_full_threshold,
+                'surplus_watts': settings.home_assistant_surplus_threshold_watts,
+            },
+            'reason': 'Energy gate open' if allowed else 'Battery or surplus threshold not met',
+        }
+
+    def health_check_sync(self) -> dict:
+        """Return current Home Assistant connectivity and queue gate diagnostics."""
+        if not self.base_url:
+            return {
+                'status': 'error',
+                'message': 'Home Assistant URL is not configured.',
+                'base_url': '',
+                'configured': False,
+                'checks': [],
+            }
+        if not self.token:
+            return {
+                'status': 'error',
+                'message': 'Home Assistant token is not configured.',
+                'base_url': self.base_url,
+                'configured': False,
+                'checks': [],
+            }
+        battery = self._get_state_sync(settings.home_assistant_battery_entity_id)
+        surplus = self._get_state_sync(settings.home_assistant_surplus_entity_id)
+        checks = []
+        for name, entity_id, payload in (
+            ('battery', settings.home_assistant_battery_entity_id, battery),
+            ('surplus', settings.home_assistant_surplus_entity_id, surplus),
+        ):
+            checks.append(
+                {
+                    'name': name,
+                    'entity_id': entity_id,
+                    'ok': not bool(payload.get('error')),
+                    'message': str(payload.get('error') or payload.get('state') or 'ok'),
+                    'status_code': payload.get('status_code'),
+                    'url': self._state_url(entity_id) if entity_id else self.base_url,
+                }
+            )
+        return {
+            'status': 'success' if all(check['ok'] for check in checks) else 'error',
+            'message': 'Home Assistant connectivity is healthy.' if all(check['ok'] for check in checks) else 'Home Assistant checks failed.',
+            'base_url': self.base_url,
+            'configured': True,
+            'checks': checks,
+            'queue_gate': {
+                'battery_full_percent': settings.home_assistant_battery_full_threshold,
+                'surplus_watts': settings.home_assistant_surplus_threshold_watts,
+                'force_process': settings.prompt_queue_force_process,
+            },
+        }

ai_software_factory/agents/llm_service.py

@@ -0,0 +1,394 @@
+"""Centralized LLM client with guardrails and mediated tool context."""
+
+from __future__ import annotations
+
+import json
+
+try:
+    from .gitea import GiteaAPI
+except ImportError:
+    from gitea import GiteaAPI
+
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
+
+class LLMToolbox:
+    """Build named tool payloads that can be shared with external LLM providers."""
+
+    SUPPORTED_LIVE_TOOL_STAGES = ('request_interpretation', 'change_summary', 'generation_plan', 'project_naming', 'project_id_naming')
+
+    def build_tool_context(self, stage: str, context: dict | None = None) -> list[dict]:
+        """Return the mediated tool payloads allowed for this LLM request."""
+        context = context or {}
+        allowed = set(settings.llm_tool_allowlist)
+        limit = settings.llm_tool_context_limit
+        tool_context: list[dict] = []
+
+        if 'gitea_project_catalog' in allowed:
+            projects = context.get('projects') or []
+            if projects:
+                tool_context.append(
+                    {
+                        'name': 'gitea_project_catalog',
+                        'description': 'Tracked active projects and their repository mappings inside the factory.',
+                        'payload': projects[:limit],
+                    }
+                )
+
+        if 'gitea_project_state' in allowed:
+            state_payload = {
+                'project_id': context.get('project_id'),
+                'project_name': context.get('project_name') or context.get('name'),
+                'repository': context.get('repository'),
+                'repository_url': context.get('repository_url'),
+                'pull_request': context.get('pull_request'),
+                'pull_request_url': context.get('pull_request_url'),
+                'pull_request_state': context.get('pull_request_state'),
+                'related_issue': context.get('related_issue'),
+            }
+            if any(value for value in state_payload.values()):
+                tool_context.append(
+                    {
+                        'name': 'gitea_project_state',
+                        'description': 'Current repository and pull-request state for the project being discussed.',
+                        'payload': state_payload,
+                    }
+                )
+
+        if 'gitea_project_issues' in allowed:
+            issues = context.get('open_issues') or context.get('issues') or []
+            if issues:
+                tool_context.append(
+                    {
+                        'name': 'gitea_project_issues',
+                        'description': 'Open tracked Gitea issues for the relevant project repository.',
+                        'payload': issues[:limit],
+                    }
+                )
+
+        if 'gitea_pull_requests' in allowed:
+            pull_requests = context.get('pull_requests') or []
+            if pull_requests:
+                tool_context.append(
+                    {
+                        'name': 'gitea_pull_requests',
+                        'description': 'Tracked pull requests associated with the relevant project repository.',
+                        'payload': pull_requests[:limit],
+                    }
+                )
+
+        return tool_context
+
+    def build_live_tool_specs(self, stage: str, context: dict | None = None) -> list[dict]:
+        """Return live tool-call specs that the model may request explicitly."""
+        _context = context or {}
+        specs = []
+        allowed = set(settings.llm_live_tools_for_stage(stage))
+        if 'gitea_lookup_issue' in allowed:
+            specs.append(
+                {
+                    'name': 'gitea_lookup_issue',
+                    'description': 'Fetch one live Gitea issue by issue number for a tracked repository.',
+                    'arguments': {
+                        'project_id': 'optional tracked project id',
+                        'owner': 'optional repository owner override',
+                        'repo': 'optional repository name override',
+                        'issue_number': 'required integer issue number',
+                    },
+                }
+            )
+        if 'gitea_lookup_pull_request' in allowed:
+            specs.append(
+                {
+                    'name': 'gitea_lookup_pull_request',
+                    'description': 'Fetch one live Gitea pull request by PR number for a tracked repository.',
+                    'arguments': {
+                        'project_id': 'optional tracked project id',
+                        'owner': 'optional repository owner override',
+                        'repo': 'optional repository name override',
+                        'pr_number': 'required integer pull request number',
+                    },
+                }
+            )
+        return specs
+
+
+class LLMLiveToolExecutor:
+    """Resolve bounded live tool requests on behalf of the model."""
+
+    def __init__(self):
+        self.gitea_api = None
+        if settings.gitea_url and settings.gitea_token:
+            self.gitea_api = GiteaAPI(
+                token=settings.GITEA_TOKEN,
+                base_url=settings.GITEA_URL,
+                owner=settings.GITEA_OWNER,
+                repo=settings.GITEA_REPO or '',
+            )
+
+    async def execute(self, tool_name: str, arguments: dict, context: dict | None = None) -> dict:
+        """Execute one live tool request and normalize the result."""
+        if tool_name not in set(settings.llm_live_tool_allowlist):
+            return {'error': f'Tool {tool_name} is not enabled'}
+        if self.gitea_api is None:
+            return {'error': 'Gitea live tool execution is not configured'}
+        resolved = self._resolve_repository(arguments=arguments, context=context or {})
+        if resolved.get('error'):
+            return resolved
+        owner = resolved['owner']
+        repo = resolved['repo']
+
+        if tool_name == 'gitea_lookup_issue':
+            issue_number = arguments.get('issue_number')
+            if issue_number is None:
+                return {'error': 'issue_number is required'}
+            return await self.gitea_api.get_issue(issue_number=int(issue_number), owner=owner, repo=repo)
+
+        if tool_name == 'gitea_lookup_pull_request':
+            pr_number = arguments.get('pr_number')
+            if pr_number is None:
+                return {'error': 'pr_number is required'}
+            return await self.gitea_api.get_pull_request(pr_number=int(pr_number), owner=owner, repo=repo)
+
+        return {'error': f'Unsupported tool {tool_name}'}
+
+    def _resolve_repository(self, arguments: dict, context: dict) -> dict:
+        """Resolve repository owner/name from explicit args or tracked project context."""
+        owner = arguments.get('owner')
+        repo = arguments.get('repo')
+        if owner and repo:
+            return {'owner': owner, 'repo': repo}
+        project_id = arguments.get('project_id')
+        if project_id:
+            for project in context.get('projects', []):
+                if project.get('project_id') == project_id:
+                    repository = project.get('repository') or {}
+                    if repository.get('owner') and repository.get('name'):
+                        return {'owner': repository['owner'], 'repo': repository['name']}
+            state = context.get('repository') or {}
+            if context.get('project_id') == project_id and state.get('owner') and state.get('name'):
+                return {'owner': state['owner'], 'repo': state['name']}
+        repository = context.get('repository') or {}
+        if repository.get('owner') and repository.get('name'):
+            return {'owner': repository['owner'], 'repo': repository['name']}
+        return {'error': 'Could not resolve repository for tool request'}
+
+
+class LLMServiceClient:
+    """Call the configured LLM provider with consistent guardrails and tool payloads."""
+
+    def __init__(self, ollama_url: str | None = None, model: str | None = None):
+        self.ollama_url = (ollama_url or settings.ollama_url).rstrip('/')
+        self.model = model or settings.OLLAMA_MODEL
+        self.toolbox = LLMToolbox()
+        self.live_tool_executor = LLMLiveToolExecutor()
+
+    async def chat_with_trace(
+        self,
+        *,
+        stage: str,
+        system_prompt: str,
+        user_prompt: str,
+        tool_context_input: dict | None = None,
+        expect_json: bool = False,
+    ) -> tuple[str | None, dict]:
+        """Invoke the configured LLM and return both content and a structured trace."""
+        effective_system_prompt = self._compose_system_prompt(stage, system_prompt)
+        tool_context = self.toolbox.build_tool_context(stage=stage, context=tool_context_input)
+        live_tool_specs = self.toolbox.build_live_tool_specs(stage=stage, context=tool_context_input)
+        effective_user_prompt = self._compose_user_prompt(user_prompt, tool_context, live_tool_specs)
+        raw_responses: list[dict] = []
+        executed_tool_calls: list[dict] = []
+        current_user_prompt = effective_user_prompt
+        max_rounds = settings.llm_max_tool_call_rounds
+
+        for round_index in range(max_rounds + 1):
+            content, payload, error = await self._send_chat_request(
+                system_prompt=effective_system_prompt,
+                user_prompt=current_user_prompt,
+                expect_json=expect_json,
+            )
+            raw_responses.append(payload)
+            if content:
+                tool_request = self._extract_tool_request(content)
+                if tool_request and round_index < max_rounds:
+                    tool_name = tool_request.get('name')
+                    tool_arguments = tool_request.get('arguments') or {}
+                    tool_result = await self.live_tool_executor.execute(tool_name, tool_arguments, tool_context_input)
+                    executed_tool_calls.append(
+                        {
+                            'name': tool_name,
+                            'arguments': tool_arguments,
+                            'result': tool_result,
+                        }
+                    )
+                    current_user_prompt = self._compose_follow_up_prompt(user_prompt, tool_context, live_tool_specs, executed_tool_calls)
+                    continue
+                return content, {
+                    'stage': stage,
+                    'provider': 'ollama',
+                    'model': self.model,
+                    'system_prompt': effective_system_prompt,
+                    'user_prompt': current_user_prompt,
+                    'assistant_response': content,
+                    'raw_response': {
+                        'provider_response': raw_responses[-1],
+                        'provider_responses': raw_responses,
+                        'tool_context': tool_context,
+                        'live_tool_specs': live_tool_specs,
+                        'executed_tool_calls': executed_tool_calls,
+                    },
+                    'raw_responses': raw_responses,
+                    'fallback_used': False,
+                    'guardrails': self._guardrail_sections(stage),
+                    'tool_context': tool_context,
+                    'live_tool_specs': live_tool_specs,
+                    'executed_tool_calls': executed_tool_calls,
+                }
+            if error:
+                break
+
+        return None, {
+            'stage': stage,
+            'provider': 'ollama',
+            'model': self.model,
+            'system_prompt': effective_system_prompt,
+            'user_prompt': current_user_prompt,
+            'assistant_response': '',
+            'raw_response': {
+                'provider_response': raw_responses[-1] if raw_responses else {'error': 'No response'},
+                'provider_responses': raw_responses,
+                'tool_context': tool_context,
+                'live_tool_specs': live_tool_specs,
+                'executed_tool_calls': executed_tool_calls,
+            },
+            'raw_responses': raw_responses,
+            'fallback_used': True,
+            'guardrails': self._guardrail_sections(stage),
+            'tool_context': tool_context,
+            'live_tool_specs': live_tool_specs,
+            'executed_tool_calls': executed_tool_calls,
+        }
+
+    async def _send_chat_request(self, *, system_prompt: str, user_prompt: str, expect_json: bool) -> tuple[str | None, dict, str | None]:
+        """Send one outbound chat request to the configured model provider."""
+        request_payload = {
+            'model': self.model,
+            'stream': False,
+            'messages': [
+                {'role': 'system', 'content': system_prompt},
+                {'role': 'user', 'content': user_prompt},
+            ],
+        }
+        if expect_json:
+            request_payload['format'] = 'json'
+        try:
+            import aiohttp
+
+            async with aiohttp.ClientSession() as session:
+                async with session.post(f'{self.ollama_url}/api/chat', json=request_payload) as resp:
+                    payload = await resp.json()
+                    if 200 <= resp.status < 300:
+                        return (payload.get('message') or {}).get('content', ''), payload, None
+                    return None, payload, str(payload.get('error') or payload)
+        except Exception as exc:
+            return None, {'error': str(exc)}, str(exc)
+
+    def _compose_system_prompt(self, stage: str, stage_prompt: str) -> str:
+        """Merge the stage prompt with configured guardrails."""
+        sections = [stage_prompt.strip()] + self._guardrail_sections(stage)
+        return '\n\n'.join(section for section in sections if section)
+
+    def _guardrail_sections(self, stage: str) -> list[str]:
+        """Return all configured guardrail sections for one LLM stage."""
+        sections = []
+        if settings.llm_guardrail_prompt:
+            sections.append(f'Global guardrails:\n{settings.llm_guardrail_prompt}')
+        stage_specific = {
+            'request_interpretation': settings.llm_request_interpreter_guardrail_prompt,
+            'change_summary': settings.llm_change_summary_guardrail_prompt,
+            'project_naming': settings.llm_project_naming_guardrail_prompt,
+            'project_id_naming': settings.llm_project_id_guardrail_prompt,
+        }.get(stage)
+        if stage_specific:
+            sections.append(f'Stage-specific guardrails:\n{stage_specific}')
+        return sections
+
+    def _compose_user_prompt(self, prompt: str, tool_context: list[dict], live_tool_specs: list[dict] | None = None) -> str:
+        """Append tool payloads and live tool-call specs to the outbound user prompt."""
+        live_tool_specs = live_tool_specs if live_tool_specs is not None else []
+        sections = [prompt]
+        if not tool_context:
+            pass
+        else:
+            sections.append(
+                'Service-mediated tool outputs are available below. Treat them as authoritative read-only data supplied by the factory:\n'
+                f'{json.dumps(tool_context, indent=2, sort_keys=True)}'
+            )
+        if live_tool_specs:
+            sections.append(
+                'If you need additional live repository data, you may request exactly one tool call by responding with JSON shaped as '
+                '{"tool_request": {"name": "<tool name>", "arguments": {...}}}. '
+                'After tool results are returned, respond with the final answer instead of another tool request.\n'
+                f'Available live tools:\n{json.dumps(live_tool_specs, indent=2, sort_keys=True)}'
+            )
+        return '\n\n'.join(section for section in sections if section)
+
+    def _compose_follow_up_prompt(self, original_prompt: str, tool_context: list[dict], live_tool_specs: list[dict], executed_tool_calls: list[dict]) -> str:
+        """Build the follow-up user prompt after executing one or more live tool requests."""
+        sections = [self._compose_user_prompt(original_prompt, tool_context, live_tool_specs)]
+        sections.append(
+            'The service executed the requested live tool call(s). Use the tool result(s) below to produce the final answer. Do not request another tool call.\n'
+            f'{json.dumps(executed_tool_calls, indent=2, sort_keys=True)}'
+        )
+        return '\n\n'.join(sections)
+
+    def _extract_tool_request(self, content: str) -> dict | None:
+        """Return a normalized tool request when the model explicitly asks for one."""
+        try:
+            parsed = json.loads(content)
+        except Exception:
+            return None
+        if not isinstance(parsed, dict):
+            return None
+        tool_request = parsed.get('tool_request')
+        if not isinstance(tool_request, dict) or not tool_request.get('name'):
+            return None
+        return {
+            'name': str(tool_request.get('name')).strip(),
+            'arguments': tool_request.get('arguments') or {},
+        }
+
+    def get_runtime_configuration(self) -> dict:
+        """Return the active LLM runtime config, guardrails, and tool exposure."""
+        live_tool_stages = {
+            stage: settings.llm_live_tools_for_stage(stage)
+            for stage in self.toolbox.SUPPORTED_LIVE_TOOL_STAGES
+        }
+        return {
+            'provider': 'ollama',
+            'ollama_url': self.ollama_url,
+            'model': self.model,
+            'guardrails': {
+                'global': settings.llm_guardrail_prompt,
+                'request_interpretation': settings.llm_request_interpreter_guardrail_prompt,
+                'change_summary': settings.llm_change_summary_guardrail_prompt,
+                'project_naming': settings.llm_project_naming_guardrail_prompt,
+                'project_id_naming': settings.llm_project_id_guardrail_prompt,
+            },
+            'system_prompts': {
+                'project_naming': settings.llm_project_naming_system_prompt,
+                'project_id_naming': settings.llm_project_id_system_prompt,
+            },
+            'mediated_tools': settings.llm_tool_allowlist,
+            'live_tools': settings.llm_live_tool_allowlist,
+            'live_tool_stage_allowlist': settings.llm_live_tool_stage_allowlist,
+            'live_tool_stage_tool_map': settings.llm_live_tool_stage_tool_map,
+            'live_tools_by_stage': live_tool_stages,
+            'tool_context_limit': settings.llm_tool_context_limit,
+            'max_tool_call_rounds': settings.llm_max_tool_call_rounds,
+            'gitea_live_tools_configured': bool(settings.gitea_url and settings.gitea_token),
+        }

ai_software_factory/agents/n8n_setup.py

@@ -1,7 +1,13 @@
 """n8n setup agent for automatic webhook configuration."""
 
 import json
+from urllib import error as urllib_error
+from urllib import request as urllib_request
 from typing import Optional
+
+try:
+    from ..config import settings
+except ImportError:
     from config import settings
 
 
@@ -22,95 +28,426 @@ class N8NSetupAgent:
         self.webhook_token = webhook_token
         self.session = None
 
+    def _api_path(self, path: str) -> str:
+        """Build a full n8n API URL for a given endpoint path."""
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        trimmed = path.lstrip("/")
+        if trimmed.startswith("api/"):
+            return f"{self.api_url}/{trimmed}"
+        return f"{self.api_url}/api/v1/{trimmed}"
+    
     def get_auth_headers(self) -> dict:
         """Get authentication headers for n8n API using webhook token."""
-        return {
+        headers = {
             "n8n-no-credentials": "true",
             "Content-Type": "application/json",
             "User-Agent": "AI-Software-Factory"
         }
+        if self.webhook_token:
+            headers["X-N8N-API-KEY"] = self.webhook_token
+        return headers
+
+    def _extract_message(self, payload: object) -> str:
+        """Extract a useful message from an n8n response payload."""
+        if isinstance(payload, dict):
+            for key in ("message", "error", "reason", "hint", "text"):
+                value = payload.get(key)
+                if value:
+                    return str(value)
+            if payload:
+                return json.dumps(payload)
+        if payload is None:
+            return "No response body"
+        return str(payload)
+
+    def _normalize_success(self, method: str, url: str, status_code: int, payload: object) -> dict:
+        """Normalize a successful n8n API response."""
+        if isinstance(payload, dict):
+            response = dict(payload)
+            response.setdefault("status_code", status_code)
+            response.setdefault("url", url)
+            response.setdefault("method", method)
+            return response
+        return {"data": payload, "status_code": status_code, "url": url, "method": method}
+
+    def _normalize_error(self, method: str, url: str, status_code: int | None, payload: object) -> dict:
+        """Normalize an error response with enough detail for diagnostics."""
+        message = self._extract_message(payload)
+        prefix = f"{method} {url}"
+        if status_code is not None:
+            return {
+                "error": f"{prefix} returned {status_code}: {message}",
+                "message": message,
+                "status_code": status_code,
+                "url": url,
+                "method": method,
+                "payload": payload,
+            }
+        return {
+            "error": f"{prefix} failed: {message}",
+            "message": message,
+            "status_code": None,
+            "url": url,
+            "method": method,
+            "payload": payload,
+        }
+
+    def _health_check_row(self, name: str, result: dict) -> dict:
+        """Convert a raw request result into a UI/API-friendly health check row."""
+        return {
+            "name": name,
+            "ok": not bool(result.get("error")),
+            "url": result.get("url"),
+            "method": result.get("method", "GET"),
+            "status_code": result.get("status_code"),
+            "message": result.get("message") or ("ok" if not result.get("error") else result.get("error")),
+        }
+
+    def _health_suggestion(self, checks: list[dict]) -> str | None:
+        """Return a suggestion based on failed n8n health checks."""
+        status_codes = {check.get("status_code") for check in checks if check.get("status_code") is not None}
+        if status_codes and status_codes.issubset({404}):
+            return "Verify N8N_API_URL points to the base n8n URL, for example http://host:5678, not /api/v1 or a webhook URL."
+        if status_codes & {401, 403}:
+            return "Check the configured n8n API key or authentication method."
+        return "Verify the n8n URL, API key, and that the n8n API is reachable from this container."
+
+    def _build_health_result(self, healthz_result: dict, workflows_result: dict) -> dict:
+        """Build a consolidated health result from the performed checks."""
+        checks = [
+            self._health_check_row("healthz", healthz_result),
+            self._health_check_row("workflows", workflows_result),
+        ]
+
+        if not healthz_result.get("error"):
+            return {
+                "status": "ok",
+                "message": "n8n is reachable via /healthz.",
+                "api_url": self.api_url,
+                "auth_configured": bool(self.webhook_token),
+                "checked_via": "healthz",
+                "checks": checks,
+            }
+
+        if not workflows_result.get("error"):
+            workflows = workflows_result.get("data")
+            workflow_count = len(workflows) if isinstance(workflows, list) else None
+            return {
+                "status": "ok",
+                "message": "n8n is reachable via the workflows API, but /healthz is unavailable.",
+                "api_url": self.api_url,
+                "auth_configured": bool(self.webhook_token),
+                "checked_via": "workflows",
+                "workflow_count": workflow_count,
+                "checks": checks,
+            }
+
+        suggestion = self._health_suggestion(checks)
+        return {
+            "status": "error",
+            "error": "n8n health checks failed",
+            "message": "n8n health checks failed.",
+            "api_url": self.api_url,
+            "auth_configured": bool(self.webhook_token),
+            "checked_via": "none",
+            "checks": checks,
+            "suggestion": suggestion,
+        }
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Send a request to n8n and normalize the response."""
+        import aiohttp
+
+        headers = kwargs.pop("headers", None) or self.get_auth_headers()
+        url = self._api_path(path)
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.request(method, url, headers=headers, **kwargs) as resp:
+                    content_type = resp.headers.get("Content-Type", "")
+                    if "application/json" in content_type:
+                        payload = await resp.json()
+                    else:
+                        payload = {"text": await resp.text()}
+
+                    if 200 <= resp.status < 300:
+                        return self._normalize_success(method, url, resp.status, payload)
+
+                    return self._normalize_error(method, url, resp.status, payload)
+        except Exception as e:
+            return self._normalize_error(method, url, None, {"message": str(e)})
+
+    def _request_sync(self, method: str, path: str, **kwargs) -> dict:
+        """Send a synchronous request to n8n for dashboard health snapshots."""
+        headers = kwargs.pop("headers", None) or self.get_auth_headers()
+        payload = kwargs.pop("json", None)
+        timeout = kwargs.pop("timeout", 5)
+        url = self._api_path(path)
+        data = None
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+        req = urllib_request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib_request.urlopen(req, timeout=timeout) as resp:
+                raw_body = resp.read().decode("utf-8")
+                content_type = resp.headers.get("Content-Type", "")
+                if "application/json" in content_type and raw_body:
+                    parsed = json.loads(raw_body)
+                elif raw_body:
+                    parsed = {"text": raw_body}
+                else:
+                    parsed = {}
+                return self._normalize_success(method, url, resp.status, parsed)
+        except urllib_error.HTTPError as exc:
+            raw_body = exc.read().decode("utf-8") if exc.fp else ""
+            try:
+                parsed = json.loads(raw_body) if raw_body else {}
+            except json.JSONDecodeError:
+                parsed = {"text": raw_body} if raw_body else {}
+            return self._normalize_error(method, url, exc.code, parsed)
+        except Exception as exc:
+            return self._normalize_error(method, url, None, {"message": str(exc)})
     
     async def get_workflow(self, workflow_name: str) -> Optional[dict]:
         """Get a workflow by name."""
-        import aiohttp
+        workflows = await self.list_workflows()
-        try:
+        if isinstance(workflows, dict) and workflows.get("error"):
-            async with aiohttp.ClientSession() as session:
+            return workflows
-                # Use the webhook URL directly for workflow operations
+        for workflow in workflows:
-                # n8n supports calling workflows via /webhook/ path with query params
+            if workflow.get("name") == workflow_name:
-                # For API token auth, n8n checks the token against webhook credentials
+                return workflow
-                headers = self.get_auth_headers()
-                
-                # Try standard workflow endpoint first (for API token setup)
-                async with session.get(
-                    f"{self.api_url}/workflow/{workflow_name}.json",
-                    headers=headers
-                ) as resp:
-                    if resp.status == 200:
-                        return await resp.json()
-                    elif resp.status == 404:
         return None
-                    else:
-                        return {"error": f"Status {resp.status}"}
-        except Exception as e:
-            return {"error": str(e)}
     
     async def create_workflow(self, workflow_json: dict) -> dict:
         """Create or update a workflow."""
-        import aiohttp
+        return await self._request("POST", "workflows", json=self._workflow_payload(workflow_json))
-        try:
-            async with aiohttp.ClientSession() as session:
-                # Use POST to create/update workflow
-                headers = self.get_auth_headers()
 
-                async with session.post(
+    def _workflow_payload(self, workflow_json: dict) -> dict:
-                    f"{self.api_url}/workflow",
+        """Return a workflow payload without server-managed read-only fields."""
-                    headers=headers,
+        payload = dict(workflow_json)
-                    json=workflow_json
+        payload.pop("active", None)
-                ) as resp:
+        payload.pop("id", None)
-                    if resp.status == 200 or resp.status == 201:
+        payload.pop("createdAt", None)
-                        return await resp.json()
+        payload.pop("updatedAt", None)
-                    else:
+        payload.pop("versionId", None)
-                        return {"error": f"Status {resp.status}: {await resp.text()}"}
+        return payload
-        except Exception as e:
+
-            return {"error": str(e)}
+    async def _update_workflow_via_put(self, workflow_id: str, workflow_json: dict) -> dict:
+        """Fallback update path for n8n instances that only support PUT."""
+        return await self._request("PUT", f"workflows/{workflow_id}", json=self._workflow_payload(workflow_json))
+
+    async def update_workflow(self, workflow_id: str, workflow_json: dict) -> dict:
+        """Update an existing workflow."""
+        result = await self._request("PATCH", f"workflows/{workflow_id}", json=self._workflow_payload(workflow_json))
+        if result.get("status_code") == 405:
+            fallback = await self._update_workflow_via_put(workflow_id, workflow_json)
+            if not fallback.get("error") and isinstance(fallback, dict):
+                fallback.setdefault("method", "PUT")
+            return fallback
+        return result
     
     async def enable_workflow(self, workflow_id: str) -> dict:
         """Enable a workflow."""
-        import aiohttp
+        result = await self._request("POST", f"workflows/{workflow_id}/activate")
-        try:
+        if result.get("error"):
-            async with aiohttp.ClientSession() as session:
+            fallback = await self._request("PATCH", f"workflows/{workflow_id}", json={"active": True})
-                headers = self.get_auth_headers()
+            if fallback.get("error"):
-                
+                if fallback.get("status_code") == 405:
-                async with session.post(
+                    put_fallback = await self._request("PUT", f"workflows/{workflow_id}", json={"active": True})
-                    f"{self.api_url}/workflow/{workflow_id}/toggle",
+                    if put_fallback.get("error"):
-                    headers=headers,
+                        return put_fallback
-                    json={"state": True}
+                    return {"success": True, "id": workflow_id, "method": "put"}
-                ) as resp:
+                return fallback
-                    if resp.status in (200, 201):
+            return {"success": True, "id": workflow_id, "method": "patch"}
-                        return {"success": True, "id": workflow_id}
+        return {"success": True, "id": workflow_id, "method": "activate"}
-                    else:
-                        return {"error": f"Status {resp.status}: {await resp.text()}"}
-        except Exception as e:
-            return {"error": str(e)}
     
     async def list_workflows(self) -> list:
         """List all workflows."""
-        import aiohttp
+        result = await self._request("GET", "workflows")
-        try:
+        if result.get("error"):
-            async with aiohttp.ClientSession() as session:
+            return result
-                headers = self.get_auth_headers()
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            for key in ("data", "workflows"):
+                value = result.get(key)
+                if isinstance(value, list):
+                    return value
+        return []
 
-                async with session.get(
+    def build_telegram_workflow(self, webhook_path: str, backend_url: str, allowed_chat_id: str | None = None) -> dict:
-                    f"{self.api_url}/workflow",
+        """Build the Telegram-to-backend workflow definition."""
-                    headers=headers
+        normalized_path = webhook_path.strip().strip("/") or "telegram"
-                ) as resp:
+        allowed_chat = json.dumps(str(allowed_chat_id)) if allowed_chat_id else "''"
-                    if resp.status == 200:
+        return {
-                        return await resp.json()
+            "name": "Telegram to AI Software Factory",
-                    else:
+            "settings": {"executionOrder": "v1"},
+            "nodes": [
+                {
+                    "id": "webhook-node",
+                    "name": "Telegram Webhook",
+                    "type": "n8n-nodes-base.webhook",
+                    "typeVersion": 2,
+                    "position": [-520, 120],
+                    "parameters": {
+                        "httpMethod": "POST",
+                        "path": normalized_path,
+                        "responseMode": "responseNode",
+                        "options": {},
+                    },
+                },
+                {
+                    "id": "parse-node",
+                    "name": "Prepare Freeform Request",
+                    "type": "n8n-nodes-base.code",
+                    "typeVersion": 2,
+                    "position": [-200, 120],
+                    "parameters": {
+                        "language": "javaScript",
+                        "jsCode": f"const allowedChatId = {allowed_chat};\nconst body = $json.body ?? $json;\nconst message = body.message ?? body;\nconst text = String(message.text ?? '').trim();\nconst chatId = String(message.chat?.id ?? '');\nif (allowedChatId && chatId !== allowedChatId) {{\n  return [{{ json: {{ ignored: true, message: `Ignoring message from chat ${{chatId}}`, prompt_text: text, source: 'telegram', chat_id: chatId, chat_type: message.chat?.type ?? null }} }}];\n}}\nreturn [{{ json: {{ prompt_text: text, source: 'telegram', chat_id: chatId, chat_type: message.chat?.type ?? null }} }}];",
+                    },
+                },
+                {
+                    "id": "api-node",
+                    "name": "AI Software Factory API",
+                    "type": "n8n-nodes-base.httpRequest",
+                    "typeVersion": 4.2,
+                    "position": [120, 120],
+                    "parameters": {
+                        "method": "POST",
+                        "url": backend_url,
+                        "sendBody": True,
+                        "specifyBody": "json",
+                        "jsonBody": "={{ $json }}",
+                        "options": {"response": {"response": {"fullResponse": False}}},
+                    },
+                },
+                {
+                    "id": "response-node",
+                    "name": "Respond to Telegram Webhook",
+                    "type": "n8n-nodes-base.respondToWebhook",
+                    "typeVersion": 1.2,
+                    "position": [420, 120],
+                    "parameters": {
+                        "respondWith": "json",
+                        "responseBody": "={{ $json }}",
+                    },
+                },
+            ],
+            "connections": {
+                "Telegram Webhook": {"main": [[{"node": "Prepare Freeform Request", "type": "main", "index": 0}]]},
+                "Prepare Freeform Request": {"main": [[{"node": "AI Software Factory API", "type": "main", "index": 0}]]},
+                "AI Software Factory API": {"main": [[{"node": "Respond to Telegram Webhook", "type": "main", "index": 0}]]},
+            },
+        }
+
+    def build_telegram_trigger_workflow(
+        self,
+        backend_url: str,
+        credential_name: str,
+        allowed_chat_id: str | None = None,
+    ) -> dict:
+        """Build a production Telegram Trigger based workflow."""
+        allowed_chat = json.dumps(str(allowed_chat_id)) if allowed_chat_id else "''"
+        return {
+            "name": "Telegram to AI Software Factory",
+            "settings": {"executionOrder": "v1"},
+            "nodes": [
+                {
+                    "id": "telegram-trigger-node",
+                    "name": "Telegram Trigger",
+                    "type": "n8n-nodes-base.telegramTrigger",
+                    "typeVersion": 1,
+                    "position": [-520, 120],
+                    "parameters": {"updates": ["message", "channel_post"]},
+                    "credentials": {"telegramApi": {"name": credential_name}},
+                },
+                {
+                    "id": "filter-node",
+                    "name": "Prepare Freeform Request",
+                    "type": "n8n-nodes-base.code",
+                    "typeVersion": 2,
+                    "position": [-180, 120],
+                    "parameters": {
+                        "language": "javaScript",
+                        "jsCode": f"const allowedChatId = {allowed_chat};\nconst message = $json.message ?? $json.channel_post ?? $json;\nconst text = String(message.text ?? '').trim();\nconst chatId = String(message.chat?.id ?? '');\nif (!text) return [];\nif (allowedChatId && chatId !== allowedChatId) return [];\nreturn [{{ json: {{ prompt_text: text, source: 'telegram', chat_id: chatId, chat_type: message.chat?.type ?? null }} }}];",
+                    },
+                },
+                {
+                    "id": "api-node",
+                    "name": "AI Software Factory API",
+                    "type": "n8n-nodes-base.httpRequest",
+                    "typeVersion": 4.2,
+                    "position": [120, 120],
+                    "parameters": {
+                        "method": "POST",
+                        "url": backend_url,
+                        "sendBody": True,
+                        "specifyBody": "json",
+                        "jsonBody": "={{ $json }}",
+                        "options": {"response": {"response": {"fullResponse": False}}},
+                    },
+                },
+                {
+                    "id": "reply-node",
+                    "name": "Send Telegram Update",
+                    "type": "n8n-nodes-base.telegram",
+                    "typeVersion": 1,
+                    "position": [420, 120],
+                    "parameters": {
+                        "resource": "message",
+                        "operation": "sendMessage",
+                        "chatId": "={{ ($('Telegram Trigger').item.json.message ?? $('Telegram Trigger').item.json.channel_post).chat.id }}",
+                        "text": "={{ $json.summary_message || $json.data?.summary_message || $json.message || 'Software generation request accepted' }}",
+                    },
+                    "credentials": {"telegramApi": {"name": credential_name}},
+                },
+            ],
+            "connections": {
+                "Telegram Trigger": {"main": [[{"node": "Prepare Freeform Request", "type": "main", "index": 0}]]},
+                "Prepare Freeform Request": {"main": [[{"node": "AI Software Factory API", "type": "main", "index": 0}]]},
+                "AI Software Factory API": {"main": [[{"node": "Send Telegram Update", "type": "main", "index": 0}]]},
+            },
+        }
+
+    async def list_credentials(self) -> list:
+        """List n8n credentials."""
+        result = await self._request("GET", "credentials")
+        if result.get("error"):
             return []
-        except Exception as e:
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            for key in ("data", "credentials"):
+                value = result.get(key)
+                if isinstance(value, list):
+                    return value
         return []
 
+    async def get_credential(self, credential_name: str, credential_type: str = "telegramApi") -> Optional[dict]:
+        """Get an existing credential by name and type."""
+        credentials = await self.list_credentials()
+        for credential in credentials:
+            if credential.get("name") == credential_name and credential.get("type") == credential_type:
+                return credential
+        return None
+
+    async def create_credential(self, name: str, credential_type: str, data: dict) -> dict:
+        """Create an n8n credential."""
+        payload = {"name": name, "type": credential_type, "data": data}
+        return await self._request("POST", "credentials", json=payload)
+
+    async def ensure_telegram_credential(self, bot_token: str, credential_name: str) -> dict:
+        """Ensure a Telegram credential exists for the workflow trigger."""
+        existing = await self.get_credential(credential_name)
+        if existing:
+            return existing
+        return await self.create_credential(
+            name=credential_name,
+            credential_type="telegramApi",
+            data={"accessToken": bot_token},
+        )
+    
     async def setup_telegram_workflow(self, webhook_path: str) -> dict:
         """Setup the Telegram webhook workflow in n8n.
         
@@ -120,117 +457,95 @@ class N8NSetupAgent:
         Returns:
             Result of setup operation
         """
-        import os
+        return await self.setup(
-        webhook_token = os.getenv("TELEGRAM_BOT_TOKEN", "")
+            webhook_path=webhook_path,
-        
+            backend_url=f"{settings.backend_public_url}/generate/text",
-        # Define the workflow using n8n's Telegram trigger
+            force_update=False,
-        workflow = {
+        )
-            "name": "Telegram to AI Software Factory",
-            "nodes": [
-                {
-                    "parameters": {
-                        "httpMethod": "post",
-                        "responseMode": "response",
-                        "path": webhook_path or "telegram",
-                        "httpBody": "={{ json.stringify($json) }}",
-                        "httpAuthType": "headerParam",
-                        "headerParams": {
-                            "x-n8n-internal": "true",
-                            "content-type": "application/json"
-                        }
-                    },
-                    "id": "webhook-node",
-                    "name": "Telegram Webhook"
-                },
-                {
-                    "parameters": {
-                        "operation": "editFields",
-                        "fields": "json",
-                        "editFieldsValue": "={{ json.parse($json.text) }}",
-                        "options": {}
-                    },
-                    "id": "parse-node",
-                    "name": "Parse Message"
-                },
-                {
-                    "parameters": {
-                        "url": "http://localhost:8000/generate",
-                        "method": "post",
-                        "sendBody": True,
-                        "responseMode": "onReceived",
-                        "ignoreSSL": True,
-                        "retResponse": True,
-                        "sendQueryParams": False
-                    },
-                    "id": "api-node",
-                    "name": "AI Software Factory API"
-                },
-                {
-                    "parameters": {
-                        "operation": "editResponse",
-                        "editResponseValue": "={{ $json }}"
-                    },
-                    "id": "response-node",
-                    "name": "Response Builder"
-                }
-            ],
-            "connections": {
-                "Telegram Webhook": {
-                    "webhook": ["parse"]
-                },
-                "Parse Message": {
-                    "API Call": ["POST"]
-                },
-                "Response Builder": {
-                    "respondToWebhook": ["response"]
-                }
-            },
-            "settings": {
-                "executionOrder": "v1"
-            }
-        }
-        
-        # Create the workflow
-        result = await self.create_workflow(workflow)
-        
-        if result.get("success") or result.get("id"):
-            # Try to enable the workflow
-            enable_result = await self.enable_workflow(result.get("id", ""))
-            result.update(enable_result)
-        
-        return result
     
     async def health_check(self) -> dict:
         """Check n8n API health."""
-        import aiohttp
+        result = await self._request("GET", f"{self.api_url}/healthz")
-        try:
+        fallback = await self._request("GET", "workflows")
-            async with aiohttp.ClientSession() as session:
+        return self._build_health_result(result, fallback)
-                headers = self.get_auth_headers()
 
-                async with session.get(
+    def health_check_sync(self) -> dict:
-                    f"{self.api_url}/api/v1/workflow",
+        """Synchronously check n8n API health for UI rendering."""
-                    headers=headers
+        result = self._request_sync("GET", f"{self.api_url}/healthz")
-                ) as resp:
+        fallback = self._request_sync("GET", "workflows")
-                    if resp.status == 200:
+        return self._build_health_result(result, fallback)
-                        return {"status": "ok"}
-                    else:
-                        return {"error": f"Status {resp.status}"}
-        except Exception as e:
-            return {"error": str(e)}
     
-    async def setup(self) -> dict:
+    async def setup(
+        self,
+        webhook_path: str = "telegram",
+        backend_url: str | None = None,
+        force_update: bool = False,
+        use_telegram_trigger: bool | None = None,
+        telegram_bot_token: str | None = None,
+        telegram_credential_name: str | None = None,
+    ) -> dict:
         """Setup n8n webhooks automatically."""
         # First, verify n8n is accessible
         health = await self.health_check()
         if health.get("error"):
-            return {"status": "error", "message": health.get("error")}
+            return {
+                "status": "error",
+                "message": health.get("message") or health.get("error"),
+                "health": health,
+                "checks": health.get("checks", []),
+                "suggestion": health.get("suggestion"),
+            }
         
-        # Try to get existing telegram workflow
+        effective_backend_url = backend_url or f"{settings.backend_public_url}/generate/text"
-        existing = await self.get_workflow("Telegram to AI Software Factory")
+        effective_bot_token = telegram_bot_token or settings.telegram_bot_token
-        if existing and not existing.get("error"):
+        effective_credential_name = telegram_credential_name or settings.n8n_telegram_credential_name
-            # Enable existing workflow
+        trigger_mode = use_telegram_trigger if use_telegram_trigger is not None else bool(effective_bot_token)
-            return await self.enable_workflow(existing.get("id", ""))
 
-        # Create new workflow
+        if trigger_mode:
-        result = await self.setup_telegram_workflow("/webhook/telegram")
+            credential = await self.ensure_telegram_credential(effective_bot_token, effective_credential_name)
-        return result
+            if credential.get("error"):
+                return {"status": "error", "message": credential["error"], "details": credential}
+            workflow = self.build_telegram_trigger_workflow(
+                backend_url=effective_backend_url,
+                credential_name=effective_credential_name,
+                allowed_chat_id=settings.telegram_chat_id,
+            )
+        else:
+            workflow = self.build_telegram_workflow(
+                webhook_path=webhook_path,
+                backend_url=effective_backend_url,
+                allowed_chat_id=settings.telegram_chat_id,
+            )
+
+        existing = await self.get_workflow(workflow["name"])
+        if isinstance(existing, dict) and existing.get("error"):
+            return {"status": "error", "message": existing["error"], "details": existing}
+
+        workflow_id = None
+        if existing and existing.get("id"):
+            workflow_id = str(existing["id"])
+            if force_update:
+                result = await self.update_workflow(workflow_id, workflow)
+            else:
+                result = existing
+        else:
+            result = await self.create_workflow(workflow)
+            workflow_id = str(result.get("id", "")) if isinstance(result, dict) else None
+
+        if isinstance(result, dict) and result.get("error"):
+            return {"status": "error", "message": result["error"], "details": result}
+
+        workflow_id = workflow_id or str(result.get("id", ""))
+        enable_result = await self.enable_workflow(workflow_id)
+        if enable_result.get("error"):
+            return {"status": "error", "message": enable_result["error"], "workflow": result, "details": enable_result}
+
+        return {
+            "status": "success",
+            "message": f'Workflow "{workflow["name"]}" is active',
+            "workflow_id": workflow_id,
+            "workflow_name": workflow["name"],
+            "webhook_path": webhook_path.strip().strip("/") or "telegram",
+            "backend_url": effective_backend_url,
+            "trigger_mode": "telegram" if trigger_mode else "webhook",
+        }

ai_software_factory/agents/orchestrator.py

@@ -1,14 +1,26 @@
 """Agent orchestrator for software generation."""
 
-import asyncio
+from __future__ import annotations
+
+import difflib
+import py_compile
+import re
+import subprocess
 from typing import Optional
-from agents.git_manager import GitManager
-from agents.ui_manager import UIManager
-from agents.gitea import GiteaAPI
-from agents.database_manager import DatabaseManager
-from config import settings
 from datetime import datetime
-import os
+
+try:
+    from ..config import settings
+    from .database_manager import DatabaseManager
+    from .git_manager import GitManager
+    from .gitea import GiteaAPI
+    from .ui_manager import UIManager
+except ImportError:
+    from config import settings
+    from agents.database_manager import DatabaseManager
+    from agents.git_manager import GitManager
+    from agents.gitea import GiteaAPI
+    from agents.ui_manager import UIManager
 
 
 class AgentOrchestrator:
@@ -21,7 +33,14 @@ class AgentOrchestrator:
         description: str,
         features: list,
         tech_stack: list,
-        db = None
+        db=None,
+        prompt_text: str | None = None,
+        prompt_actor: str = "api",
+        existing_history=None,
+        prompt_source_context: dict | None = None,
+        prompt_routing: dict | None = None,
+        repo_name_override: str | None = None,
+        related_issue_hint: dict | None = None,
     ):
         """Initialize orchestrator."""
         self.project_id = project_id
@@ -36,76 +55,485 @@ class AgentOrchestrator:
         self.logs = []
         self.ui_data = {}
         self.db = db
-
+        self.prompt_text = prompt_text
-        # Initialize agents
+        self.prompt_actor = prompt_actor
-        self.git_manager = GitManager(project_id)
+        self.prompt_source_context = prompt_source_context or {}
-        self.ui_manager = UIManager(project_id)
+        self.prompt_routing = prompt_routing or {}
+        self.repo_name_override = repo_name_override
+        self.existing_history = existing_history
+        self.changed_files: list[str] = []
+        self.pending_code_changes: list[dict] = []
         self.gitea_api = GiteaAPI(
             token=settings.GITEA_TOKEN,
             base_url=settings.GITEA_URL,
             owner=settings.GITEA_OWNER,
             repo=settings.GITEA_REPO or ""
         )
+        self.project_root = settings.projects_root / project_id
+        self.prompt_audit = None
+        self.repo_name = settings.gitea_repo or self.gitea_api.build_project_repo_name(project_id, repo_name_override or project_name)
+        self.repo_owner = settings.gitea_owner
+        self.repo_url = None
+        self.branch_name = self._build_pr_branch_name(project_id)
+        self.active_pull_request = None
+        self._gitea_username: str | None = None
+        hinted_issue_number = (related_issue_hint or {}).get('number') if related_issue_hint else None
+        self.related_issue_number = hinted_issue_number if hinted_issue_number is not None else self._extract_issue_number(prompt_text)
+        self.related_issue: dict | None = DatabaseManager._normalize_issue(related_issue_hint)
+
+        # Initialize agents
+        self.git_manager = GitManager(project_id, project_dir=str(self.project_root))
+        self.ui_manager = UIManager(project_id)
 
         # Initialize database manager if db session provided
         self.db_manager = None
         self.history = None
         if db:
             self.db_manager = DatabaseManager(db)
-            # Log project start to database
+            if existing_history is not None:
+                self.history = existing_history
+                self.project_id = existing_history.project_id
+                self.project_name = existing_history.project_name or project_name
+                self.description = existing_history.description or description
+            else:
                 self.history = self.db_manager.log_project_start(
                     project_id=project_id,
                     project_name=project_name,
                     description=description
                 )
-            # Re-fetch with new history_id
                 self.db_manager = DatabaseManager(db)
+            self.active_pull_request = self.db_manager.get_open_pull_request(project_id=self.project_id)
+            if existing_history is not None and self.history is not None:
+                latest_ui = self.db_manager._get_latest_ui_snapshot_data(self.history.id)
+                repository = latest_ui.get('repository') if isinstance(latest_ui, dict) else None
+                if isinstance(repository, dict) and repository:
+                    self.repo_owner = repository.get('owner') or self.repo_owner
+                    self.repo_name = repository.get('name') or self.repo_name
+                    self.repo_url = repository.get('url') or self.repo_url
+            if self.prompt_text:
+                self.prompt_audit = self.db_manager.log_prompt_submission(
+                    history_id=self.history.id,
+                    project_id=self.project_id,
+                    prompt_text=self.prompt_text,
+                    features=self.features,
+                    tech_stack=self.tech_stack,
+                    actor_name=self.prompt_actor,
+                    related_issue={'number': self.related_issue_number} if self.related_issue_number is not None else None,
+                    source_context=self.prompt_source_context,
+                    routing=self.prompt_routing,
+                )
+
+        self.ui_manager.ui_data["project_root"] = str(self.project_root)
+        self.ui_manager.ui_data["features"] = list(self.features)
+        self.ui_manager.ui_data["tech_stack"] = list(self.tech_stack)
+        self.ui_manager.ui_data["repository"] = {
+            "owner": self.repo_owner,
+            "name": self.repo_name,
+            "mode": "project" if settings.use_project_repositories else "shared",
+            "status": "pending" if settings.use_project_repositories else "shared",
+            "provider": "gitea",
+        }
+        if self.related_issue:
+            self.ui_manager.ui_data["related_issue"] = self.related_issue
+        if self.active_pull_request:
+            self.ui_manager.ui_data["pull_request"] = self.active_pull_request
+
+    def _build_pr_branch_name(self, project_id: str) -> str:
+        """Build a stable branch name used until the PR is merged."""
+        return f"ai/{project_id}"
+
+    def _extract_issue_number(self, prompt_text: str | None) -> int | None:
+        """Extract an issue reference from prompt text."""
+        if not prompt_text:
+            return None
+        match = re.search(r'(?:#|issue\s+)(\d+)', prompt_text, flags=re.IGNORECASE)
+        return int(match.group(1)) if match else None
+
+    def _build_repo_url(self, owner: str | None, repo: str | None) -> str | None:
+        if not owner or not repo or not settings.gitea_url:
+            return None
+        return f"{settings.gitea_url.rstrip('/')}/{owner}/{repo}"
+
+    def _log_generation_plan_trace(self) -> None:
+        """Persist the current generation plan as an inspectable trace."""
+        if not self.db_manager or not self.history or not self.prompt_audit:
+            return
+        planned_files = list(self._template_files().keys())
+        self.db_manager.log_llm_trace(
+            project_id=self.project_id,
+            history_id=self.history.id,
+            prompt_id=self.prompt_audit.id,
+            stage='generation_plan',
+            provider='factory-planner',
+            model='template-generator',
+            system_prompt='Plan the generated project structure from the structured request and repository state.',
+            user_prompt=self.prompt_text or self.description,
+            assistant_response=(
+                f"Planned files: {', '.join(planned_files)}. "
+                f"Target branch: {self.branch_name}. "
+                f"Repository mode: {self.ui_manager.ui_data.get('repository', {}).get('mode', 'unknown')}."
+                + (
+                    f" Linked issue: #{self.related_issue.get('number')} {self.related_issue.get('title')}."
+                    if self.related_issue else ''
+                )
+            ),
+            raw_response={
+                'planned_files': planned_files,
+                'features': list(self.features),
+                'tech_stack': list(self.tech_stack),
+                'branch': self.branch_name,
+                'repository': self.ui_manager.ui_data.get('repository', {}),
+                'related_issue': self.related_issue,
+            },
+            fallback_used=False,
+        )
+
+    async def _sync_issue_context(self) -> None:
+        """Sync repository issues and resolve a linked issue from the prompt when present."""
+        if not self.db_manager or not self.history:
+            return
+        repository = self.ui_manager.ui_data.get('repository') or {}
+        owner = repository.get('owner') or self.repo_owner
+        repo_name = repository.get('name') or self.repo_name
+        if not owner or not repo_name or not settings.gitea_url or not settings.gitea_token:
+            return
+        issues_result = self.db_manager.sync_repository_issues(project_id=self.project_id, gitea_api=self.gitea_api, state='open')
+        self.ui_manager.ui_data['issues'] = issues_result.get('issues', []) if issues_result.get('status') == 'success' else []
+        if self.related_issue_number is None:
+            return
+        issue_payload = await self.gitea_api.get_issue(issue_number=self.related_issue_number, owner=owner, repo=repo_name)
+        if isinstance(issue_payload, dict) and issue_payload.get('error'):
+            return
+        if issue_payload.get('pull_request'):
+            return
+        self.related_issue = DatabaseManager._normalize_issue(issue_payload)
+        self.ui_manager.ui_data['related_issue'] = self.related_issue
+        if self.prompt_audit:
+            self.db_manager.attach_issue_to_prompt(self.prompt_audit.id, self.related_issue)
+
+    async def _ensure_remote_repository(self) -> None:
+        if not settings.use_project_repositories:
+            self.ui_manager.ui_data["repository"]["status"] = "shared"
+            if settings.gitea_repo:
+                predicted_url = self._build_repo_url(self.repo_owner, self.repo_name)
+                if predicted_url:
+                    self.repo_url = predicted_url
+                    self.ui_manager.ui_data["repository"]["url"] = predicted_url
+            self.ui_manager.ui_data["repository"]["api_response"] = {
+                "status": "shared",
+                "detail": "Using the configured shared repository instead of provisioning a per-project repo.",
+            }
+            return
+        if not self.repo_owner or not settings.gitea_token or not settings.gitea_url:
+            self.ui_manager.ui_data["repository"]["status"] = "skipped"
+            self.ui_manager.ui_data["repository"]["reason"] = "Missing Gitea owner, URL, or token configuration"
+            self.ui_manager.ui_data["repository"]["api_response"] = {
+                "status": "skipped",
+                "detail": "Missing Gitea owner, URL, or token configuration",
+            }
+            return
+
+        repo_name = self.repo_name
+        result = await self.gitea_api.create_repo(
+            repo_name=repo_name,
+            owner=self.repo_owner,
+            description=f"AI-generated project for {self.project_name}",
+            auto_init=False,
+        )
+        if result.get("status") == "exists" and repo_name == self.gitea_api.build_project_repo_name(self.project_id, self.project_name):
+            repo_name = f"{repo_name}-{self.project_id.split('-')[-1]}"
+            result = await self.gitea_api.create_repo(
+                repo_name=repo_name,
+                owner=self.repo_owner,
+                description=f"AI-generated project for {self.project_name}",
+                auto_init=False,
+            )
+            self.repo_name = repo_name
+            self.ui_manager.ui_data["repository"]["name"] = repo_name
+        if self.db_manager:
+            self.db_manager.log_system_event(
+                component="gitea",
+                level="ERROR" if result.get("error") else "INFO",
+                message=(
+                    f"Repository setup failed for {self.repo_owner}/{self.repo_name}: {result.get('error')}"
+                    if result.get("error")
+                    else f"Prepared repository {self.repo_owner}/{self.repo_name}"
+                ),
+            )
+        repo_status = result.get("status", "error" if result.get("error") else "ready")
+        self.ui_manager.ui_data["repository"]["status"] = repo_status
+        self.ui_manager.ui_data["repository"]["api_response"] = {
+            key: value
+            for key, value in result.items()
+            if key not in {"private"}
+        }
+        if result.get("status_code") is not None:
+            self.ui_manager.ui_data["repository"]["api_status_code"] = result.get("status_code")
+        if result.get("error"):
+            self.ui_manager.ui_data["repository"]["reason"] = result.get("error")
+            self.ui_manager.ui_data["repository"].pop("url", None)
+        elif result.get("html_url"):
+            self.repo_url = result["html_url"]
+            self.ui_manager.ui_data["repository"]["url"] = self.repo_url
+            clone_url = result.get("clone_url") or self.gitea_api.build_repo_git_url(self.repo_owner, self.repo_name)
+            if clone_url:
+                self.ui_manager.ui_data["repository"]["clone_url"] = clone_url
+            self.ui_manager.ui_data["repository"].pop("reason", None)
+        elif repo_status == "exists":
+            predicted_url = self._build_repo_url(self.repo_owner, self.repo_name)
+            if predicted_url:
+                self.repo_url = predicted_url
+                self.ui_manager.ui_data["repository"]["url"] = predicted_url
+            clone_url = result.get("clone_url") or self.gitea_api.build_repo_git_url(self.repo_owner, self.repo_name)
+            if clone_url:
+                self.ui_manager.ui_data["repository"]["clone_url"] = clone_url
+        else:
+            self.ui_manager.ui_data["repository"].pop("url", None)
+
+    async def _resolve_gitea_username(self) -> str:
+        """Resolve and cache the Gitea login used for authenticated git operations."""
+        if self._gitea_username:
+            return self._gitea_username
+        user_info = await self.gitea_api.get_current_user()
+        if user_info.get('error') or not user_info.get('login'):
+            raise RuntimeError(f"Unable to resolve Gitea user for push: {user_info.get('error', 'missing login')}")
+        self._gitea_username = user_info['login']
+        return self._gitea_username
+
+    async def _push_branch(self, branch: str) -> dict | None:
+        """Push a branch to the configured project repository when available."""
+        repository = self.ui_manager.ui_data.get('repository') or {}
+        if repository.get('mode') != 'project':
+            return None
+        if repository.get('status') not in {'created', 'exists', 'ready'}:
+            return None
+        if not settings.gitea_token or not self.repo_owner or not self.repo_name:
+            return None
+
+        clone_url = repository.get('clone_url') or self.gitea_api.build_repo_git_url(self.repo_owner, self.repo_name)
+        if not clone_url:
+            return None
+        username = await self._resolve_gitea_username()
+        self.git_manager.push_with_credentials(
+            remote_url=clone_url,
+            username=username,
+            password=settings.gitea_token,
+            remote='origin',
+            branch=branch,
+        )
+        return {'status': 'pushed', 'remote': clone_url, 'branch': branch}
+
+    async def _prepare_git_workspace(self) -> None:
+        """Initialize the local repo and ensure the PR branch exists before writing files."""
+        if not self.git_manager.is_git_available():
+            self.ui_manager.ui_data.setdefault('git', {})['error'] = 'git executable is not available in PATH'
+            self._append_log('Local git workspace skipped: git executable is not available in PATH')
+            return
+        if not self.git_manager.has_repo():
+            self.git_manager.init_repo()
+
+        if not self.git_manager.current_head_or_none():
+            self.git_manager.create_empty_commit('Initialize project repository')
+            try:
+                await self._push_branch('main')
+            except (RuntimeError, subprocess.CalledProcessError, FileNotFoundError) as exc:
+                self.ui_manager.ui_data.setdefault('git', {})['remote_error'] = str(exc)
+                self._append_log(f'Initial main push skipped: {exc}')
+
+        if self.git_manager.branch_exists(self.branch_name):
+            self.git_manager.checkout_branch(self.branch_name)
+        else:
+            self.git_manager.checkout_branch(self.branch_name, create=True, start_point='main')
+        self.ui_manager.ui_data.setdefault('git', {})['active_branch'] = self.branch_name
+
+    async def _ensure_pull_request(self) -> dict | None:
+        """Create the project pull request on first delivery and reuse it later."""
+        if self.active_pull_request:
+            self.ui_manager.ui_data['pull_request'] = self.active_pull_request
+            return self.active_pull_request
+        repository = self.ui_manager.ui_data.get('repository') or {}
+        if repository.get('mode') != 'project' or repository.get('status') not in {'created', 'exists', 'ready'}:
+            return None
+
+        title = f"AI delivery for {self.project_name}"
+        body = (
+            f"Automated software factory changes for {self.project_name}.\n\n"
+            f"Prompt: {self.prompt_text or self.description}\n\n"
+            f"Branch: {self.branch_name}"
+        )
+        result = await self.gitea_api.create_pull_request(
+            title=title,
+            body=body,
+            owner=self.repo_owner,
+            repo=self.repo_name,
+            base='main',
+            head=self.branch_name,
+        )
+        if result.get('error'):
+            raise RuntimeError(f"Unable to create pull request: {result.get('error')}")
+
+        pr_number = result.get('number') or result.get('id') or 0
+        pr_data = {
+            'pr_number': pr_number,
+            'title': result.get('title', title),
+            'body': result.get('body', body),
+            'state': result.get('state', 'open'),
+            'base': result.get('base', {}).get('ref', 'main') if isinstance(result.get('base'), dict) else 'main',
+            'user': result.get('user', {}).get('login', 'system') if isinstance(result.get('user'), dict) else 'system',
+            'pr_url': result.get('html_url') or self.gitea_api.build_pull_request_url(pr_number, self.repo_owner, self.repo_name),
+            'merged': bool(result.get('merged')),
+            'pr_state': result.get('state', 'open'),
+        }
+        if self.db_manager and self.history:
+            self.db_manager.save_pr_data(self.history.id, pr_data)
+        self.active_pull_request = self.db_manager.get_open_pull_request(project_id=self.project_id) if self.db_manager else pr_data
+        self.ui_manager.ui_data['pull_request'] = self.active_pull_request or pr_data
+        return self.active_pull_request or pr_data
+
+    async def _push_remote_commit(self, commit_hash: str, commit_message: str, changed_files: list[str], base_commit: str | None) -> dict | None:
+        """Push the local commit to the provisioned Gitea repository and build browser links."""
+        repository = self.ui_manager.ui_data.get("repository") or {}
+        if repository.get("mode") != "project":
+            return None
+        if repository.get("status") not in {"created", "exists", "ready"}:
+            return None
+        push_result = await self._push_branch(self.branch_name)
+        if push_result is None:
+            return None
+        pull_request = await self._ensure_pull_request()
+        commit_url = self.gitea_api.build_commit_url(commit_hash, owner=self.repo_owner, repo=self.repo_name)
+        compare_url = self.gitea_api.build_compare_url(base_commit, commit_hash, owner=self.repo_owner, repo=self.repo_name) if base_commit else None
+        remote_record = {
+            "status": "pushed",
+            "remote": push_result.get('remote'),
+            "branch": self.branch_name,
+            "commit_url": commit_url,
+            "compare_url": compare_url,
+            "changed_files": changed_files,
+            "pull_request": pull_request,
+        }
+        self.ui_manager.ui_data.setdefault("git", {})["remote_push"] = remote_record
+        repository["last_commit_url"] = commit_url
+        if compare_url:
+            repository["last_compare_url"] = compare_url
+        self._append_log(f"Pushed generated commit to {self.repo_owner}/{self.repo_name}.")
+        return remote_record
+
+    def _build_diff_text(self, relative_path: str, previous_content: str, new_content: str) -> str:
+        """Build a unified diff for display in the dashboard."""
+        previous_lines = previous_content.splitlines(keepends=True)
+        new_lines = new_content.splitlines(keepends=True)
+        diff = difflib.unified_diff(
+            previous_lines,
+            new_lines,
+            fromfile=f"a/{relative_path}",
+            tofile=f"b/{relative_path}",
+        )
+        return "".join(diff)
+
+    def _append_log(self, message: str) -> None:
+        timestamped = f"[{datetime.utcnow().isoformat()}] {message}"
+        self.logs.append(timestamped)
+        if self.db_manager and self.history:
+            self.db_manager._log_action(self.history.id, "INFO", message)
+
+    def _update_progress(self, progress: int, step: str, message: str) -> None:
+        self.progress = progress
+        self.current_step = step
+        self.message = message
+        self.ui_manager.update_status(self.status, progress, message)
+        if self.db_manager and self.history:
+            self.db_manager.log_progress_update(
+                history_id=self.history.id,
+                progress=progress,
+                step=step,
+                message=message,
+            )
+
+    def _write_file(self, relative_path: str, content: str) -> None:
+        target = self.project_root / relative_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        change_type = "UPDATE" if target.exists() else "CREATE"
+        previous_content = target.read_text(encoding="utf-8") if target.exists() else ""
+        diff_text = self._build_diff_text(relative_path, previous_content, content)
+        target.write_text(content, encoding="utf-8")
+        self.changed_files.append(relative_path)
+        self.pending_code_changes.append(
+            {
+                'change_type': change_type,
+                'file_path': relative_path,
+                'details': f"{change_type.title()}d generated artifact {relative_path}",
+                'diff_summary': f"Wrote {len(content.splitlines())} lines to {relative_path}",
+                'diff_text': diff_text,
+            }
+        )
+
+    def _template_files(self) -> dict[str, str]:
+        feature_section = "\n".join(f"- {feature}" for feature in self.features) or "- None specified"
+        tech_section = "\n".join(f"- {tech}" for tech in self.tech_stack) or "- Python"
+        return {
+            ".gitignore": "__pycache__/\n*.pyc\n.venv/\n.pytest_cache/\n.mypy_cache/\n",
+            "README.md": (
+                f"# {self.project_name}\n\n"
+                f"{self.description}\n\n"
+                "## Features\n"
+                f"{feature_section}\n\n"
+                "## Tech Stack\n"
+                f"{tech_section}\n"
+            ),
+            "requirements.txt": "fastapi\nuvicorn\npytest\n",
+            "main.py": (
+                "from fastapi import FastAPI\n\n"
+                "app = FastAPI(title=\"Generated App\")\n\n"
+                "@app.get('/')\n"
+                "def read_root():\n"
+                f"    return {{'name': '{self.project_name}', 'status': 'generated', 'features': {self.features!r}}}\n"
+            ),
+            "tests/test_app.py": (
+                "from main import read_root\n\n"
+                "def test_read_root():\n"
+                f"    assert read_root()['name'] == '{self.project_name}'\n"
+            ),
+        }
 
     async def run(self) -> dict:
         """Run the software generation process with full audit logging."""
         try:
             # Step 1: Initialize project
-            self.progress = 5
+            self.status = "running"
-            self.current_step = "Initializing project"
+            self._update_progress(5, "initializing", "Setting up project structure...")
-            self.message = "Setting up project structure..."
+            self._append_log("Initializing project.")
-            self.logs.append(f"[{datetime.utcnow().isoformat()}] Initializing project.")
+
+            await self._ensure_remote_repository()
+            await self._sync_issue_context()
+            await self._prepare_git_workspace()
+            self._log_generation_plan_trace()
 
             # Step 2: Create project structure (skip git operations)
-            self.progress = 15
+            self._update_progress(20, "project-structure", "Creating project files...")
-            self.current_step = "Creating project structure"
-            self.message = "Creating project files..."
             await self._create_project_structure()
 
             # Step 3: Generate initial code
-            self.progress = 25
+            self._update_progress(55, "code-generation", "Generating project entrypoint and tests...")
-            self.current_step = "Generating initial code"
-            self.message = "Generating initial code with Ollama..."
             await self._generate_code()
 
             # Step 4: Test the code
-            self.progress = 50
+            self._update_progress(80, "validation", "Validating generated code...")
-            self.current_step = "Testing code"
-            self.message = "Running tests..."
             await self._run_tests()
 
-            # Step 5: Commit to git (skip in test env)
+            # Step 5: Commit generated artifacts locally for traceability
-            self.progress = 75
+            self._update_progress(90, "git", "Recording generated changes in git...")
-            self.current_step = "Committing to git"
+            await self._commit_to_git()
-            self.message = "Skipping git operations in test environment..."
-
-            # Step 6: Create PR (skip in test env)
-            self.progress = 90
-            self.current_step = "Creating PR"
-            self.message = "Skipping PR creation in test environment..."
 
             # Step 7: Complete
-            self.progress = 100
+            self.status = "completed"
-            self.current_step = "Completed"
+            self._update_progress(100, "completed", "Software generation complete!")
-            self.message = "Software generation complete!"
+            self._append_log("Software generation complete!")
-            self.logs.append(f"[{datetime.utcnow().isoformat()}] Software generation complete!")
+            self.ui_manager.ui_data["changed_files"] = list(dict.fromkeys(self.changed_files))
 
             # Log completion to database if available
             if self.db_manager and self.history:
+                self.db_manager.save_ui_snapshot(self.history.id, self.ui_manager.get_ui_data())
                 self.db_manager.log_project_complete(
                     history_id=self.history.id,
                     message="Software generation complete!"
@@ -118,13 +546,18 @@ class AgentOrchestrator:
                 "current_step": self.current_step,
                 "logs": self.logs,
                 "ui_data": self.ui_manager.ui_data,
-                "history_id": self.history.id if self.history else None
+                "history_id": self.history.id if self.history else None,
+                "project_root": str(self.project_root),
+                "changed_files": list(dict.fromkeys(self.changed_files)),
+                "repository": self.ui_manager.ui_data.get("repository"),
+                "related_issue": self.related_issue,
+                "pull_request": self.ui_manager.ui_data.get("pull_request"),
             }
 
         except Exception as e:
             self.status = "error"
             self.message = f"Error: {str(e)}"
-            self.logs.append(f"[{datetime.utcnow().isoformat()}] Error: {str(e)}")
+            self._append_log(f"Error: {str(e)}")
 
             # Log error to database if available
             if self.db_manager and self.history:
@@ -141,68 +574,127 @@ class AgentOrchestrator:
                 "logs": self.logs,
                 "error": str(e),
                 "ui_data": self.ui_manager.ui_data,
-                "history_id": self.history.id if self.history else None
+                "history_id": self.history.id if self.history else None,
+                "project_root": str(self.project_root),
+                "changed_files": list(dict.fromkeys(self.changed_files)),
+                "repository": self.ui_manager.ui_data.get("repository"),
+                "related_issue": self.related_issue,
+                "pull_request": self.ui_manager.ui_data.get("pull_request"),
             }
 
     async def _create_project_structure(self) -> None:
         """Create initial project structure."""
-        project_dir = self.project_id
+        self.project_root.mkdir(parents=True, exist_ok=True)
-
+        for relative_path, content in self._template_files().items():
-        # Create .gitignore
+            if relative_path.startswith("main.py") or relative_path.startswith("tests/"):
-        gitignore_path = f"{project_dir}/.gitignore"
+                continue
-        try:
+            self._write_file(relative_path, content)
-            os.makedirs(project_dir, exist_ok=True)
+        self._append_log(f"Project structure created under {self.project_root}.")
-            with open(gitignore_path, "w") as f:
-                f.write("# Python\n__pycache__/\n*.pyc\n*.pyo\n*.pyd\n.Python\n*.env\n.venv/\nnode_modules/\n.env\nbuild/\ndist/\n.pytest_cache/\n.mypy_cache/\n.coverage\nhtmlcov/\n.idea/\n.vscode/\n*.swp\n*.swo\n*~\n.DS_Store\n.git\n")
-        except Exception as e:
-            self.logs.append(f"[{datetime.utcnow().isoformat()}] Failed to create .gitignore: {str(e)}")
-
-        # Create README.md
-        readme_path = f"{project_dir}/README.md"
-        try:
-            with open(readme_path, "w") as f:
-                f.write(f"# {self.project_name}\n\n{self.description}\n\n## Features\n")
-                for feature in self.features:
-                    f.write(f"- {feature}\n")
-                f.write(f"\n## Tech Stack\n")
-                for tech in self.tech_stack:
-                    f.write(f"- {tech}\n")
-        except Exception as e:
-            self.logs.append(f"[{datetime.utcnow().isoformat()}] Failed to create README.md: {str(e)}")
 
     async def _generate_code(self) -> None:
         """Generate code using Ollama."""
-        # This would call Ollama API to generate code
+        for relative_path, content in self._template_files().items():
-        # For now, create a placeholder file
+            if relative_path in {"main.py", "tests/test_app.py"}:
-        try:
+                self._write_file(relative_path, content)
-            main_py_path = f"{self.project_id}/main.py"
+        self._append_log("Application entrypoint and smoke test generated.")
-            os.makedirs(self.project_id, exist_ok=True)
-            with open(main_py_path, "w") as f:
-                f.write("# Generated by AI Software Factory\n")
-                f.write("print('Hello, World!')\n")
-        except Exception as e:
-            self.logs.append(f"[{datetime.utcnow().isoformat()}] Failed to create main.py: {str(e)}")
-
-        # Log code change to audit trail
-        if self.db_manager and self.history:
-            self.db_manager.log_code_change(
-                project_id=self.project_id,
-                change_type="CREATE",
-                file_path="main.py",
-                actor="agent",
-                actor_type="agent",
-                details="Generated main.py file"
-            )
 
     async def _run_tests(self) -> None:
         """Run tests for the generated code."""
-        # This would run pytest or other test framework
+        py_compile.compile(str(self.project_root / "main.py"), doraise=True)
-        # For now, simulate test success
+        py_compile.compile(str(self.project_root / "tests/test_app.py"), doraise=True)
-        pass
+        self._append_log("Generated Python files compiled successfully.")
 
     async def _commit_to_git(self) -> None:
         """Commit changes to git."""
-        pass  # Skip git operations in test environment
+        unique_files = list(dict.fromkeys(self.changed_files))
+        if not unique_files:
+            return
+        if not self.git_manager.is_git_available():
+            self.ui_manager.ui_data.setdefault('git', {})['error'] = 'git executable is not available in PATH'
+            self._append_log('Git commit skipped: git executable is not available in PATH')
+            return
+
+        try:
+            if not self.git_manager.has_repo():
+                self.git_manager.init_repo()
+            base_commit = self.git_manager.current_head_or_none()
+            self.git_manager.add_files(unique_files)
+            if not self.git_manager.get_status():
+                return
+
+            commit_message = f"AI generation for prompt: {self.project_name}"
+            commit_hash = self.git_manager.commit(commit_message)
+            commit_record = {
+                "hash": commit_hash,
+                "message": commit_message,
+                "files": unique_files,
+                "timestamp": datetime.utcnow().isoformat(),
+                "scope": "local",
+                "branch": self.branch_name,
+            }
+            remote_record = None
+            try:
+                remote_record = await self._push_remote_commit(commit_hash, commit_message, unique_files, base_commit)
+            except (RuntimeError, subprocess.CalledProcessError, FileNotFoundError) as remote_exc:
+                self.ui_manager.ui_data.setdefault("git", {})["remote_error"] = str(remote_exc)
+                self._append_log(f"Remote git push skipped: {remote_exc}")
+
+            if remote_record:
+                commit_record["scope"] = "remote"
+                commit_record["commit_url"] = remote_record.get("commit_url")
+                commit_record["compare_url"] = remote_record.get("compare_url")
+                if remote_record.get('pull_request'):
+                    commit_record['pull_request'] = remote_record['pull_request']
+                    self.ui_manager.ui_data['pull_request'] = remote_record['pull_request']
+            self.ui_manager.ui_data.setdefault("git", {})["latest_commit"] = commit_record
+            self.ui_manager.ui_data.setdefault("git", {})["commits"] = [commit_record]
+            self._append_log(f"Recorded git commit {commit_hash[:12]} for generated files.")
+            if self.db_manager:
+                self.db_manager.log_commit(
+                    project_id=self.project_id,
+                    commit_message=commit_message,
+                    actor="orchestrator",
+                    actor_type="agent",
+                    history_id=self.history.id if self.history else None,
+                    prompt_id=self.prompt_audit.id if self.prompt_audit else None,
+                    commit_hash=commit_hash,
+                    changed_files=unique_files,
+                    branch=self.branch_name,
+                    commit_url=remote_record.get("commit_url") if remote_record else None,
+                    compare_url=remote_record.get("compare_url") if remote_record else None,
+                    remote_status=remote_record.get("status") if remote_record else "local-only",
+                    related_issue=self.related_issue,
+                )
+                for change in self.pending_code_changes:
+                    self.db_manager.log_code_change(
+                        project_id=self.project_id,
+                        change_type=change['change_type'],
+                        file_path=change['file_path'],
+                        actor='orchestrator',
+                        actor_type='agent',
+                        details=change['details'],
+                        history_id=self.history.id if self.history else None,
+                        prompt_id=self.prompt_audit.id if self.prompt_audit else None,
+                        diff_summary=change.get('diff_summary'),
+                        diff_text=change.get('diff_text'),
+                        commit_hash=commit_hash,
+                        remote_status=remote_record.get('status') if remote_record else 'local-only',
+                        branch=self.branch_name,
+                    )
+                self.pending_code_changes.clear()
+                if self.related_issue:
+                    self.db_manager.log_issue_work(
+                        project_id=self.project_id,
+                        history_id=self.history.id if self.history else None,
+                        prompt_id=self.prompt_audit.id if self.prompt_audit else None,
+                        issue=self.related_issue,
+                        actor='orchestrator',
+                        commit_hash=commit_hash,
+                        commit_url=remote_record.get('commit_url') if remote_record else None,
+                    )
+        except (RuntimeError, subprocess.CalledProcessError, FileNotFoundError) as exc:
+            self.ui_manager.ui_data.setdefault("git", {})["error"] = str(exc)
+            self._append_log(f"Git commit skipped: {exc}")
 
     async def _create_pr(self) -> None:
         """Create pull request."""

ai_software_factory/agents/prompt_workflow.py

@@ -0,0 +1,127 @@
+"""Helpers for prompt-level repository workflows such as undoing a prompt."""
+
+from __future__ import annotations
+
+import subprocess
+
+try:
+    from ..config import settings
+    from .database_manager import DatabaseManager
+    from .git_manager import GitManager
+    from .gitea import GiteaAPI
+except ImportError:
+    from config import settings
+    from agents.database_manager import DatabaseManager
+    from agents.git_manager import GitManager
+    from agents.gitea import GiteaAPI
+
+
+class PromptWorkflowManager:
+    """Coordinate prompt-level repository actions against git and Gitea."""
+
+    def __init__(self, db):
+        self.db_manager = DatabaseManager(db)
+        self.gitea_api = GiteaAPI(
+            token=settings.GITEA_TOKEN,
+            base_url=settings.GITEA_URL,
+            owner=settings.GITEA_OWNER,
+            repo=settings.GITEA_REPO or '',
+        )
+
+    async def undo_prompt(self, project_id: str, prompt_id: int) -> dict:
+        """Revert the commit associated with a prompt and push the revert to the PR branch."""
+        history = self.db_manager.get_project_by_id(project_id)
+        if history is None:
+            return {'status': 'error', 'message': 'Project not found'}
+
+        correlations = self.db_manager.get_prompt_change_correlations(project_id=project_id, limit=500)
+        correlation = next((item for item in correlations if item.get('prompt_id') == prompt_id), None)
+        if correlation is None:
+            return {'status': 'error', 'message': 'Prompt not found for project'}
+        if correlation.get('revert'):
+            return {'status': 'ignored', 'message': 'Prompt has already been reverted', 'revert': correlation['revert']}
+
+        original_commit = next(
+            (commit for commit in correlation.get('commits', []) if commit.get('remote_status') != 'reverted' and commit.get('commit_hash')),
+            None,
+        )
+        if original_commit is None:
+            return {'status': 'error', 'message': 'No reversible commit was recorded for this prompt'}
+
+        branch = original_commit.get('branch') or f'ai/{project_id}'
+        project_root = settings.projects_root / project_id
+        git_manager = GitManager(project_id, project_dir=str(project_root))
+        if not git_manager.has_repo():
+            return {'status': 'error', 'message': 'Local project repository is not available for undo'}
+
+        try:
+            git_manager.checkout_branch(branch)
+            previous_head = git_manager.current_head_or_none()
+            revert_commit_hash = git_manager.revert_commit(original_commit['commit_hash'])
+        except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+            return {'status': 'error', 'message': f'Unable to revert prompt commit: {exc}'}
+
+        repository = self.db_manager.get_project_audit_data(project_id).get('repository') or {}
+        commit_url = None
+        compare_url = None
+        if (
+            repository.get('mode') == 'project'
+            and repository.get('status') in {'created', 'exists', 'ready'}
+            and settings.gitea_token
+            and repository.get('owner')
+            and repository.get('name')
+        ):
+            try:
+                user_info = await self.gitea_api.get_current_user()
+                username = user_info.get('login') if isinstance(user_info, dict) else None
+                if username and not user_info.get('error'):
+                    remote_url = repository.get('clone_url') or self.gitea_api.build_repo_git_url(repository.get('owner'), repository.get('name'))
+                    if remote_url:
+                        git_manager.push_with_credentials(
+                            remote_url=remote_url,
+                            username=username,
+                            password=settings.gitea_token,
+                            branch=branch,
+                        )
+                        commit_url = self.gitea_api.build_commit_url(revert_commit_hash, repository.get('owner'), repository.get('name'))
+                        if previous_head:
+                            compare_url = self.gitea_api.build_compare_url(previous_head, revert_commit_hash, repository.get('owner'), repository.get('name'))
+            except (RuntimeError, subprocess.CalledProcessError, FileNotFoundError):
+                pass
+
+        self.db_manager.log_commit(
+            project_id=project_id,
+            commit_message=f'Revert prompt {prompt_id}',
+            actor='dashboard',
+            actor_type='user',
+            history_id=history.id,
+            prompt_id=prompt_id,
+            commit_hash=revert_commit_hash,
+            changed_files=original_commit.get('changed_files', []),
+            branch=branch,
+            commit_url=commit_url,
+            compare_url=compare_url,
+            remote_status='reverted',
+        )
+        self.db_manager.log_prompt_revert(
+            project_id=project_id,
+            prompt_id=prompt_id,
+            reverted_commit_hash=original_commit['commit_hash'],
+            revert_commit_hash=revert_commit_hash,
+            actor='dashboard',
+            commit_url=commit_url,
+        )
+        self.db_manager.log_system_event(
+            component='git',
+            level='INFO',
+            message=f'Reverted prompt {prompt_id} for project {project_id}',
+        )
+        return {
+            'status': 'success',
+            'project_id': project_id,
+            'prompt_id': prompt_id,
+            'reverted_commit_hash': original_commit['commit_hash'],
+            'revert_commit_hash': revert_commit_hash,
+            'commit_url': commit_url,
+            'compare_url': compare_url,
+        }

ai_software_factory/agents/request_interpreter.py

@@ -0,0 +1,492 @@
+"""Interpret free-form software requests into structured generation input."""
+
+from __future__ import annotations
+
+import json
+import re
+
+try:
+    from ..config import settings
+    from .gitea import GiteaAPI
+    from .llm_service import LLMServiceClient
+except ImportError:
+    from config import settings
+    from agents.gitea import GiteaAPI
+    from agents.llm_service import LLMServiceClient
+
+
+class RequestInterpreter:
+    """Use Ollama to turn free-form text into a structured software request."""
+
+    REQUEST_PREFIX_WORDS = {
+        'a', 'an', 'app', 'application', 'build', 'create', 'dashboard', 'develop', 'design', 'for', 'generate',
+        'internal', 'make', 'me', 'modern', 'need', 'new', 'our', 'platform', 'please', 'project', 'service',
+        'simple', 'site', 'start', 'system', 'the', 'tool', 'us', 'want', 'web', 'website', 'with',
+    }
+
+    REPO_NOISE_WORDS = REQUEST_PREFIX_WORDS | {'and', 'from', 'into', 'on', 'that', 'this', 'to'}
+    GENERIC_PROJECT_NAME_WORDS = {
+        'app', 'application', 'harness', 'platform', 'project', 'purpose', 'service', 'solution', 'suite', 'system', 'test', 'tool',
+    }
+    PLACEHOLDER_PROJECT_NAME_WORDS = {
+        'generated project', 'new project', 'project', 'temporary name', 'temp name', 'placeholder', 'untitled project',
+    }
+
+    def __init__(self, ollama_url: str | None = None, model: str | None = None):
+        self.ollama_url = (ollama_url or settings.ollama_url).rstrip('/')
+        self.model = model or settings.OLLAMA_MODEL
+        self.llm_client = LLMServiceClient(ollama_url=self.ollama_url, model=self.model)
+        self.gitea_api = None
+        if settings.gitea_url and settings.gitea_token:
+            self.gitea_api = GiteaAPI(
+                token=settings.GITEA_TOKEN,
+                base_url=settings.GITEA_URL,
+                owner=settings.GITEA_OWNER,
+                repo=settings.GITEA_REPO or '',
+            )
+
+    async def interpret(self, prompt_text: str, context: dict | None = None) -> dict:
+        """Interpret free-form text into the request shape expected by the orchestrator."""
+        interpreted, _trace = await self.interpret_with_trace(prompt_text, context=context)
+        return interpreted
+
+    async def interpret_with_trace(self, prompt_text: str, context: dict | None = None) -> tuple[dict, dict]:
+        """Interpret free-form text into the request shape expected by the orchestrator."""
+        normalized = prompt_text.strip()
+        if not normalized:
+            raise ValueError('Prompt text cannot be empty')
+
+        compact_context = self._build_compact_context(context or {})
+
+        system_prompt = (
+            'You route Telegram software prompts. '
+            'Decide whether the prompt starts a new project or continues an existing tracked project. '
+            'When continuing, identify the best matching project_id from the provided context and the issue number if one is mentioned or implied by recent chat history. '
+            'Return only JSON with keys request and routing. '
+            'request must contain name, description, features, tech_stack. '
+            'routing must contain intent, project_id, project_name, issue_number, confidence, and reasoning_summary. '
+            'Use the provided project catalog and recent chat history. '
+            'If the user says things like also, continue, work on this, that issue, or follow-up wording, prefer continuation of the most relevant recent project. '
+            'If the user explicitly asks for a new project, set intent to new_project.'
+        )
+        user_prompt = normalized
+        if compact_context:
+            user_prompt = (
+                f"Conversation context:\n{json.dumps(compact_context, indent=2)}\n\n"
+                f"User prompt:\n{normalized}"
+            )
+
+        content, trace = await self.llm_client.chat_with_trace(
+            stage='request_interpretation',
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            tool_context_input={
+                'projects': compact_context.get('projects', []),
+                'open_issues': [
+                    issue
+                    for project in compact_context.get('projects', [])
+                    for issue in project.get('open_issues', [])
+                ],
+                'recent_chat_history': compact_context.get('recent_chat_history', []),
+            },
+            expect_json=True,
+        )
+        if content:
+            try:
+                parsed = json.loads(content)
+                interpreted = self._normalize_interpreted_request(parsed, normalized)
+                routing = self._normalize_routing(parsed.get('routing'), interpreted, compact_context)
+                naming_trace = None
+                if routing.get('intent') == 'new_project':
+                    interpreted, routing, naming_trace = await self._refine_new_project_identity(
+                        prompt_text=normalized,
+                        interpreted=interpreted,
+                        routing=routing,
+                        context=compact_context,
+                    )
+                trace['routing'] = routing
+                trace['context_excerpt'] = compact_context
+                if naming_trace is not None:
+                    trace['project_naming'] = naming_trace
+                return interpreted, trace
+            except Exception:
+                pass
+
+        interpreted, routing = self._heuristic_fallback(normalized, compact_context)
+        if routing.get('intent') == 'new_project':
+            constraints = await self._collect_project_identity_constraints(compact_context)
+            routing['repo_name'] = self._ensure_unique_repo_name(routing.get('repo_name') or interpreted.get('name') or 'project', constraints['repo_names'])
+        return interpreted, {
+            'stage': 'request_interpretation',
+            'provider': 'heuristic',
+            'model': self.model,
+            'system_prompt': system_prompt,
+            'user_prompt': user_prompt,
+            'assistant_response': json.dumps({'request': interpreted, 'routing': routing}),
+            'raw_response': {'fallback': 'heuristic', 'llm_trace': trace.get('raw_response') if isinstance(trace, dict) else None},
+            'routing': routing,
+            'context_excerpt': compact_context,
+            'guardrails': trace.get('guardrails') if isinstance(trace, dict) else [],
+            'tool_context': trace.get('tool_context') if isinstance(trace, dict) else [],
+            'fallback_used': True,
+        }
+
+    async def _refine_new_project_identity(
+        self,
+        *,
+        prompt_text: str,
+        interpreted: dict,
+        routing: dict,
+        context: dict,
+    ) -> tuple[dict, dict, dict | None]:
+        """Refine project and repository naming for genuinely new work."""
+        constraints = await self._collect_project_identity_constraints(context)
+        user_prompt = (
+            f"Original user prompt:\n{prompt_text}\n\n"
+            f"Draft structured request:\n{json.dumps(interpreted, indent=2)}\n\n"
+            f"Tracked project names to avoid reusing unless the user clearly wants them:\n{json.dumps(sorted(constraints['project_names']))}\n\n"
+            f"Repository slugs already reserved in tracked projects or Gitea:\n{json.dumps(sorted(constraints['repo_names']))}\n\n"
+            "Suggest the best project display name and repository slug for this new project."
+        )
+        content, trace = await self.llm_client.chat_with_trace(
+            stage='project_naming',
+            system_prompt=settings.llm_project_naming_system_prompt,
+            user_prompt=user_prompt,
+            tool_context_input={
+                'projects': context.get('projects', []),
+            },
+            expect_json=True,
+        )
+        if content:
+            try:
+                fallback_name = self._preferred_project_name_fallback(prompt_text, interpreted.get('name'))
+                parsed = json.loads(content)
+                project_name, repo_name = self._normalize_project_identity(
+                    parsed,
+                    fallback_name=fallback_name,
+                )
+                repo_name = self._ensure_unique_repo_name(repo_name, constraints['repo_names'])
+                interpreted['name'] = project_name
+                routing['project_name'] = project_name
+                routing['repo_name'] = repo_name
+                return interpreted, routing, trace
+            except Exception:
+                pass
+
+        fallback_name = self._preferred_project_name_fallback(prompt_text, interpreted.get('name'))
+        routing['project_name'] = fallback_name
+        routing['repo_name'] = self._ensure_unique_repo_name(self._derive_repo_name(fallback_name), constraints['repo_names'])
+        return interpreted, routing, trace
+
+    async def _collect_project_identity_constraints(self, context: dict) -> dict[str, set[str]]:
+        """Collect reserved project names and repository slugs from tracked state and Gitea."""
+        project_names: set[str] = set()
+        repo_names: set[str] = set()
+        for project in context.get('projects', []):
+            if project.get('name'):
+                project_names.add(str(project.get('name')).strip())
+            repository = project.get('repository') or {}
+            if repository.get('name'):
+                repo_names.add(str(repository.get('name')).strip())
+        repo_names.update(await self._load_remote_repo_names())
+        return {
+            'project_names': project_names,
+            'repo_names': repo_names,
+        }
+
+    async def _load_remote_repo_names(self) -> set[str]:
+        """Load current Gitea repository names when live credentials are available."""
+        if settings.gitea_repo:
+            return {settings.gitea_repo}
+        if self.gitea_api is None or not settings.gitea_owner:
+            return set()
+        repos = await self.gitea_api.list_repositories(owner=settings.gitea_owner)
+        if not isinstance(repos, list):
+            return set()
+        return {str(repo.get('name')).strip() for repo in repos if repo.get('name')}
+
+    def _normalize_interpreted_request(self, interpreted: dict, original_prompt: str) -> dict:
+        """Normalize LLM output into the required request shape."""
+        request_payload = interpreted.get('request') if isinstance(interpreted.get('request'), dict) else interpreted
+        name = str(interpreted.get('name') or '').strip() or self._derive_name(original_prompt)
+        if isinstance(request_payload, dict):
+            name = str(request_payload.get('name') or '').strip() or self._derive_name(original_prompt)
+        description = str((request_payload or {}).get('description') or '').strip() or original_prompt[:255]
+        features = self._normalize_list((request_payload or {}).get('features'))
+        tech_stack = self._normalize_list((request_payload or {}).get('tech_stack'))
+        if not features:
+            features = ['core workflow based on free-form request']
+        return {
+            'name': name[:255],
+            'description': description[:255],
+            'features': features,
+            'tech_stack': tech_stack,
+        }
+
+    def _build_compact_context(self, context: dict) -> dict:
+        """Reduce interpreter context to the fields that help routing."""
+        projects = []
+        for project in context.get('projects', [])[:10]:
+            issues = []
+            for issue in project.get('open_issues', [])[:5]:
+                issues.append({'number': issue.get('number'), 'title': issue.get('title'), 'state': issue.get('state')})
+            projects.append(
+                {
+                    'project_id': project.get('project_id'),
+                    'name': project.get('name'),
+                    'description': project.get('description'),
+                    'repository': project.get('repository'),
+                    'open_pull_request': bool(project.get('open_pull_request')),
+                    'open_issues': issues,
+                }
+            )
+        return {
+            'chat_id': context.get('chat_id'),
+            'recent_chat_history': context.get('recent_chat_history', [])[:8],
+            'projects': projects,
+        }
+
+    def _normalize_routing(self, routing: dict | None, interpreted: dict, context: dict) -> dict:
+        """Normalize routing metadata returned by the LLM."""
+        routing = routing or {}
+        project_id = routing.get('project_id')
+        project_name = routing.get('project_name')
+        issue_number = routing.get('issue_number')
+        if issue_number in ('', None):
+            issue_number = None
+        elif isinstance(issue_number, str) and issue_number.isdigit():
+            issue_number = int(issue_number)
+        matched_project = None
+        for project in context.get('projects', []):
+            if project_id and project.get('project_id') == project_id:
+                matched_project = project
+                break
+            if project_name and project.get('name') == project_name:
+                matched_project = project
+                break
+        intent = str(routing.get('intent') or '').strip() or ('continue_project' if matched_project else 'new_project')
+        normalized = {
+            'intent': intent,
+            'project_id': matched_project.get('project_id') if matched_project else project_id,
+            'project_name': matched_project.get('name') if matched_project else (project_name or interpreted.get('name')),
+            'repo_name': routing.get('repo_name') if intent == 'new_project' else None,
+            'issue_number': issue_number,
+            'confidence': routing.get('confidence') or ('medium' if matched_project else 'low'),
+            'reasoning_summary': routing.get('reasoning_summary') or ('Matched prior project context' if matched_project else 'No strong prior project match found'),
+        }
+        if normalized['intent'] == 'new_project' and not normalized['repo_name']:
+            normalized['repo_name'] = self._derive_repo_name(normalized['project_name'] or interpreted.get('name') or 'Generated Project')
+        return normalized
+
+    def _normalize_list(self, value) -> list[str]:
+        if isinstance(value, list):
+            return [str(item).strip() for item in value if str(item).strip()]
+        if isinstance(value, str) and value.strip():
+            return [item.strip() for item in value.split(',') if item.strip()]
+        return []
+
+    def _derive_name(self, prompt_text: str) -> str:
+        """Derive a stable project name when the LLM does not provide one."""
+        first_line = prompt_text.splitlines()[0].strip()
+        quoted = re.search(r'["\']([^"\']{3,80})["\']', first_line)
+        if quoted:
+            return self._humanize_name(quoted.group(1))
+
+        noun_phrase = re.search(
+            r'(?:build|create|start|make|develop|generate|design|need|want)\s+'
+            r'(?:me\s+|us\s+|an?\s+|the\s+|new\s+|internal\s+|simple\s+|lightweight\s+|modern\s+|web\s+|mobile\s+)*'
+            r'([a-z0-9][a-z0-9\s-]{2,80}?(?:portal|dashboard|app|application|service|tool|system|platform|api|bot|assistant|website|site|workspace|tracker|manager|harness|runner|framework|suite|pipeline|lab))\b',
+            first_line,
+            flags=re.IGNORECASE,
+        )
+        if noun_phrase:
+            return self._humanize_name(noun_phrase.group(1))
+
+        focused_phrase = re.search(
+            r'(?:purpose\s+is\s+to\s+create\s+(?:an?\s+)?)'
+            r'([a-z0-9][a-z0-9\s-]{2,80}?(?:portal|dashboard|app|application|service|tool|system|platform|api|bot|assistant|website|site|workspace|tracker|manager|harness|runner|framework|suite|pipeline|lab))\b',
+            first_line,
+            flags=re.IGNORECASE,
+        )
+        if focused_phrase:
+            return self._humanize_name(focused_phrase.group(1))
+
+        cleaned = re.sub(r'[^A-Za-z0-9 ]+', ' ', first_line)
+        stopwords = {
+            'build', 'create', 'start', 'make', 'develop', 'generate', 'design', 'need', 'want', 'please', 'for', 'our', 'with', 'that', 'this',
+            'new', 'internal', 'simple', 'modern', 'web', 'mobile', 'app', 'application', 'tool', 'system',
+        }
+        tokens = [word for word in cleaned.split() if word and word.lower() not in stopwords]
+        if tokens:
+            return self._humanize_name(' '.join(tokens[:4]))
+        return 'Generated Project'
+
+    def _humanize_name(self, raw_name: str) -> str:
+        """Normalize a candidate project name into a readable title."""
+        cleaned = re.sub(r'[^A-Za-z0-9\s-]+', ' ', raw_name).strip(' -')
+        cleaned = re.sub(r'\s+', ' ', cleaned)
+        cleaned = self._trim_request_prefix(cleaned)
+        special_upper = {'api', 'crm', 'erp', 'cms', 'hr', 'it', 'ui', 'qa'}
+        words = []
+        for word in cleaned.split()[:6]:
+            lowered = word.lower()
+            words.append(lowered.upper() if lowered in special_upper else lowered.capitalize())
+        return ' '.join(words) or 'Generated Project'
+
+    def _trim_request_prefix(self, candidate: str) -> str:
+        """Remove leading request phrasing from model-produced names and slugs."""
+        tokens = [token for token in re.split(r'[-\s]+', candidate or '') if token]
+        while tokens and tokens[0].lower() in self.REQUEST_PREFIX_WORDS:
+            tokens.pop(0)
+        trimmed = ' '.join(tokens).strip()
+        return trimmed or candidate.strip()
+
+    def _derive_repo_name(self, project_name: str) -> str:
+        """Derive a repository slug from a human-readable project name."""
+        preferred_name = self._trim_request_prefix((project_name or 'project').strip())
+        preferred = preferred_name.lower().replace(' ', '-')
+        sanitized = ''.join(ch if ch.isalnum() or ch in {'-', '_'} else '-' for ch in preferred)
+        while '--' in sanitized:
+            sanitized = sanitized.replace('--', '-')
+        return sanitized.strip('-') or 'project'
+
+    def _should_use_repo_name_candidate(self, candidate: str, project_name: str) -> bool:
+        """Return whether a model-proposed repo slug is concise enough to trust directly."""
+        cleaned = self._trim_request_prefix(re.sub(r'[^A-Za-z0-9\s_-]+', ' ', candidate or '').strip())
+        if not cleaned:
+            return False
+        candidate_tokens = [token.lower() for token in re.split(r'[-\s_]+', cleaned) if token]
+        if not candidate_tokens:
+            return False
+        if len(candidate_tokens) > 6:
+            return False
+        noise_count = sum(1 for token in candidate_tokens if token in self.REPO_NOISE_WORDS)
+        if noise_count >= 2:
+            return False
+        if len('-'.join(candidate_tokens)) > 40:
+            return False
+        project_tokens = {
+            token.lower()
+            for token in re.split(r'[-\s_]+', project_name or '')
+            if token and token.lower() not in self.REPO_NOISE_WORDS
+        }
+        if project_tokens:
+            overlap = sum(1 for token in candidate_tokens if token in project_tokens)
+            if overlap == 0:
+                return False
+        return True
+
+    def _should_use_project_name_candidate(self, candidate: str, fallback_name: str) -> bool:
+        """Return whether a model-proposed project title is concrete enough to trust."""
+        cleaned = self._trim_request_prefix(re.sub(r'[^A-Za-z0-9\s-]+', ' ', candidate or '').strip())
+        if not cleaned:
+            return False
+        candidate_tokens = [token.lower() for token in re.split(r'[-\s]+', cleaned) if token]
+        if not candidate_tokens:
+            return False
+        if len(candidate_tokens) == 1 and candidate_tokens[0] in self.GENERIC_PROJECT_NAME_WORDS:
+            return False
+        if all(token in self.GENERIC_PROJECT_NAME_WORDS for token in candidate_tokens):
+            return False
+        fallback_tokens = {
+            token.lower() for token in re.split(r'[-\s]+', fallback_name or '') if token and token.lower() not in self.REPO_NOISE_WORDS
+        }
+        if fallback_tokens and len(candidate_tokens) <= 2:
+            overlap = sum(1 for token in candidate_tokens if token in fallback_tokens)
+            if overlap == 0 and any(token in self.GENERIC_PROJECT_NAME_WORDS for token in candidate_tokens):
+                return False
+        return True
+
+    def _preferred_project_name_fallback(self, prompt_text: str, interpreted_name: str | None) -> str:
+        """Pick the best fallback title when the earlier interpretation produced a placeholder."""
+        interpreted_clean = self._humanize_name(str(interpreted_name or '').strip()) if interpreted_name else ''
+        normalized_interpreted = interpreted_clean.lower()
+        if normalized_interpreted and normalized_interpreted not in self.PLACEHOLDER_PROJECT_NAME_WORDS:
+            if not (len(normalized_interpreted.split()) == 1 and normalized_interpreted in self.GENERIC_PROJECT_NAME_WORDS):
+                return interpreted_clean
+        return self._derive_name(prompt_text)
+
+    def _ensure_unique_repo_name(self, repo_name: str, reserved_names: set[str]) -> str:
+        """Choose a repository slug that does not collide with tracked or remote repositories."""
+        base_name = self._derive_repo_name(repo_name)
+        if base_name not in reserved_names:
+            return base_name
+        suffix = 2
+        while f'{base_name}-{suffix}' in reserved_names:
+            suffix += 1
+        return f'{base_name}-{suffix}'
+
+    def _normalize_project_identity(self, payload: dict, fallback_name: str) -> tuple[str, str]:
+        """Normalize model-proposed project and repository naming."""
+        fallback_project_name = self._humanize_name(str(fallback_name or 'Generated Project'))
+        project_candidate = str(payload.get('project_name') or payload.get('name') or '').strip()
+        project_name = fallback_project_name
+        if project_candidate and self._should_use_project_name_candidate(project_candidate, fallback_project_name):
+            project_name = self._humanize_name(project_candidate)
+        repo_candidate = str(payload.get('repo_name') or '').strip()
+        repo_name = self._derive_repo_name(project_name)
+        if repo_candidate and self._should_use_repo_name_candidate(repo_candidate, project_name):
+            repo_name = self._derive_repo_name(repo_candidate)
+        return project_name, repo_name
+
+    def _heuristic_fallback(self, prompt_text: str, context: dict | None = None) -> tuple[dict, dict]:
+        """Fallback request extraction when Ollama is unavailable."""
+        lowered = prompt_text.lower()
+        tech_candidates = [
+            'python', 'fastapi', 'django', 'flask', 'postgresql', 'sqlite', 'react', 'vue', 'nicegui', 'docker'
+        ]
+        tech_stack = [candidate for candidate in tech_candidates if candidate in lowered]
+        sentences = [part.strip() for part in re.split(r'[\n\.]+', prompt_text) if part.strip()]
+        features = sentences[:3] or ['Implement the user request from free-form text']
+        interpreted = {
+            'name': self._derive_name(prompt_text),
+            'description': sentences[0][:255] if sentences else prompt_text[:255],
+            'features': features,
+            'tech_stack': tech_stack,
+        }
+        routing = self._heuristic_routing(prompt_text, context or {})
+        if routing.get('project_name'):
+            interpreted['name'] = routing['project_name']
+        return interpreted, routing
+
+    def _heuristic_routing(self, prompt_text: str, context: dict) -> dict:
+        """Best-effort routing when the LLM is unavailable."""
+        lowered = prompt_text.lower()
+        explicit_new = any(token in lowered for token in ['new project', 'start a new project', 'create a new project', 'build a new app'])
+        referenced_issue = self._extract_issue_number(prompt_text)
+        recent_history = context.get('recent_chat_history', [])
+        projects = context.get('projects', [])
+        last_project_id = recent_history[0].get('project_id') if recent_history else None
+        last_issue = ((recent_history[0].get('related_issue') or {}).get('number') if recent_history else None)
+
+        matched_project = None
+        for project in projects:
+            name = (project.get('name') or '').lower()
+            repo = ((project.get('repository') or {}).get('name') or '').lower()
+            if name and name in lowered:
+                matched_project = project
+                break
+            if repo and repo in lowered:
+                matched_project = project
+                break
+        if matched_project is None and not explicit_new:
+            follow_up_tokens = ['also', 'continue', 'for this project', 'for that project', 'work on this', 'work on that', 'fix that', 'add this']
+            if any(token in lowered for token in follow_up_tokens) and last_project_id:
+                matched_project = next((project for project in projects if project.get('project_id') == last_project_id), None)
+        issue_number = referenced_issue
+        if issue_number is None and any(token in lowered for token in ['that issue', 'this issue', 'the issue']) and last_issue is not None:
+            issue_number = last_issue
+        intent = 'new_project' if explicit_new or matched_project is None else 'continue_project'
+        return {
+            'intent': intent,
+            'project_id': matched_project.get('project_id') if matched_project else None,
+            'project_name': matched_project.get('name') if matched_project else self._derive_name(prompt_text),
+            'repo_name': None if matched_project else self._derive_repo_name(self._derive_name(prompt_text)),
+            'issue_number': issue_number,
+            'confidence': 'medium' if matched_project or explicit_new else 'low',
+            'reasoning_summary': 'Heuristic routing from chat history and project names.',
+        }
+
+    def _extract_issue_number(self, prompt_text: str) -> int | None:
+        match = re.search(r'(?:#|issue\s+)(\d+)', prompt_text, flags=re.IGNORECASE)
+        return int(match.group(1)) if match else None

ai_software_factory/agents/telegram.py

@@ -1,8 +1,6 @@
 """Telegram bot integration for n8n webhook."""
 
 import asyncio
-import json
-import re
 from typing import Optional
 
 
@@ -13,6 +11,59 @@ class TelegramHandler:
         self.webhook_url = webhook_url
         self.api_url = "https://api.telegram.org/bot"
 
+    def build_prompt_guide_message(self, backend_url: str | None = None) -> str:
+        """Build a Telegram message explaining the expected prompt format."""
+        lines = [
+            "AI Software Factory is listening in this chat.",
+            "",
+            "You can send free-form software requests in normal language.",
+            "",
+            "Example:",
+            "Build an internal inventory portal for our warehouse team.",
+            "It should support role-based login, stock dashboards, and purchase orders.",
+            "Prefer FastAPI, PostgreSQL, and a simple web UI.",
+            "",
+            "The backend will interpret the request and turn it into a structured project plan.",
+        ]
+        if backend_url:
+            lines.extend(["", f"Backend target: {backend_url}"])
+        return "\n".join(lines)
+
+    async def send_message(self, bot_token: str, chat_id: str | int, text: str) -> dict:
+        """Send a direct Telegram message using the configured bot."""
+        if not bot_token:
+            return {"status": "error", "message": "Telegram bot token is not configured"}
+        if chat_id in (None, ""):
+            return {"status": "error", "message": "Telegram chat id is not configured"}
+
+        api_endpoint = f"{self.api_url}{bot_token}/sendMessage"
+
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    api_endpoint,
+                    json={
+                        "chat_id": str(chat_id),
+                        "text": text,
+                    },
+                ) as resp:
+                    payload = await resp.json()
+                    if 200 <= resp.status < 300 and payload.get("ok"):
+                        return {
+                            "status": "success",
+                            "message": "Telegram prompt guide sent successfully",
+                            "payload": payload,
+                        }
+                    description = payload.get("description") or payload.get("message") or str(payload)
+                    return {
+                        "status": "error",
+                        "message": f"Telegram API returned {resp.status}: {description}",
+                        "payload": payload,
+                    }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+    
     async def handle_message(self, message_data: dict) -> dict:
         """Handle incoming Telegram message."""
         text = message_data.get("text", "")

ai_software_factory/agents/ui_manager.py

@@ -1,5 +1,6 @@
 """UI manager for web dashboard with audit trail display."""
 
+import html
 import json
 from typing import Optional, List
 
@@ -50,14 +51,7 @@ class UIManager:
         """Escape HTML special characters for safe display."""
         if text is None:
             return ""
-        safe_chars = {
+        return html.escape(str(text), quote=True)
-            '&': '&',
-            '<': '<',
-            '>': '>',
-            '"': '"',
-            "'": '&#x27;'
-        }
-        return ''.join(safe_chars.get(c, c) for c in str(text))
     
     def render_dashboard(self, audit_trail: Optional[List[dict]] = None, 
                          actions: Optional[List[dict]] = None, 

ai_software_factory/alembic.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+path_separator = os
+sqlalchemy.url = sqlite:////tmp/ai_software_factory_test.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers = console
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

ai_software_factory/alembic/env.py

@@ -0,0 +1,50 @@
+"""Alembic environment for AI Software Factory."""
+
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+try:
+    from ai_software_factory.models import Base
+except ImportError:
+    from models import Base
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in offline mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True, compare_type=True)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in online mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

ai_software_factory/alembic/script.py.mako

@@ -0,0 +1,17 @@
+"""${message}"""
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+from alembic import op
+import sqlalchemy as sa
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

ai_software_factory/alembic/versions/20260410_01_initial_schema.py

@@ -0,0 +1,164 @@
+"""initial schema
+
+Revision ID: 20260410_01
+Revises: 
+Create Date: 2026-04-10 00:00:00
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "20260410_01"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "agent_actions",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("agent_name", sa.String(length=100), nullable=False),
+        sa.Column("action_type", sa.String(length=100), nullable=False),
+        sa.Column("success", sa.Boolean(), nullable=True),
+        sa.Column("message", sa.String(length=500), nullable=True),
+        sa.Column("timestamp", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "audit_trail",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("component", sa.String(length=50), nullable=True),
+        sa.Column("log_level", sa.String(length=50), nullable=True),
+        sa.Column("message", sa.String(length=500), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.Column("project_id", sa.String(length=255), nullable=True),
+        sa.Column("action", sa.String(length=100), nullable=True),
+        sa.Column("actor", sa.String(length=100), nullable=True),
+        sa.Column("action_type", sa.String(length=50), nullable=True),
+        sa.Column("details", sa.Text(), nullable=True),
+        sa.Column("metadata_json", sa.JSON(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "project_history",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.String(length=255), nullable=False),
+        sa.Column("project_name", sa.String(length=255), nullable=True),
+        sa.Column("features", sa.Text(), nullable=True),
+        sa.Column("description", sa.String(length=255), nullable=True),
+        sa.Column("status", sa.String(length=50), nullable=True),
+        sa.Column("progress", sa.Integer(), nullable=True),
+        sa.Column("message", sa.String(length=500), nullable=True),
+        sa.Column("current_step", sa.String(length=255), nullable=True),
+        sa.Column("total_steps", sa.Integer(), nullable=True),
+        sa.Column("current_step_description", sa.String(length=1024), nullable=True),
+        sa.Column("current_step_details", sa.Text(), nullable=True),
+        sa.Column("error_message", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.Column("started_at", sa.DateTime(), nullable=True),
+        sa.Column("updated_at", sa.DateTime(), nullable=True),
+        sa.Column("completed_at", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "system_logs",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("component", sa.String(length=50), nullable=False),
+        sa.Column("log_level", sa.String(length=50), nullable=True),
+        sa.Column("log_message", sa.String(length=500), nullable=False),
+        sa.Column("user_agent", sa.String(length=255), nullable=True),
+        sa.Column("ip_address", sa.String(length=45), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "project_logs",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("log_level", sa.String(length=50), nullable=True),
+        sa.Column("log_message", sa.String(length=500), nullable=False),
+        sa.Column("timestamp", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "prompt_code_links",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.String(length=255), nullable=False),
+        sa.Column("prompt_audit_id", sa.Integer(), nullable=False),
+        sa.Column("code_change_audit_id", sa.Integer(), nullable=False),
+        sa.Column("file_path", sa.String(length=500), nullable=True),
+        sa.Column("change_type", sa.String(length=50), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "pull_request_data",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("pr_number", sa.Integer(), nullable=False),
+        sa.Column("pr_title", sa.String(length=500), nullable=False),
+        sa.Column("pr_body", sa.Text(), nullable=True),
+        sa.Column("pr_state", sa.String(length=50), nullable=False),
+        sa.Column("pr_url", sa.String(length=500), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "pull_requests",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("pr_number", sa.Integer(), nullable=False),
+        sa.Column("pr_title", sa.String(length=500), nullable=False),
+        sa.Column("pr_body", sa.Text(), nullable=True),
+        sa.Column("base", sa.String(length=255), nullable=False),
+        sa.Column("user", sa.String(length=255), nullable=False),
+        sa.Column("pr_url", sa.String(length=500), nullable=False),
+        sa.Column("merged", sa.Boolean(), nullable=True),
+        sa.Column("merged_at", sa.DateTime(), nullable=True),
+        sa.Column("pr_state", sa.String(length=50), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "ui_snapshots",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("snapshot_data", sa.JSON(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "user_actions",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=True),
+        sa.Column("user_id", sa.String(length=100), nullable=True),
+        sa.Column("action_type", sa.String(length=100), nullable=True),
+        sa.Column("actor_type", sa.String(length=50), nullable=True),
+        sa.Column("actor_name", sa.String(length=100), nullable=True),
+        sa.Column("action_description", sa.String(length=500), nullable=True),
+        sa.Column("action_data", sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("user_actions")
+    op.drop_table("ui_snapshots")
+    op.drop_table("pull_requests")
+    op.drop_table("pull_request_data")
+    op.drop_table("prompt_code_links")
+    op.drop_table("project_logs")
+    op.drop_table("system_logs")
+    op.drop_table("project_history")
+    op.drop_table("audit_trail")
+    op.drop_table("agent_actions")

ai_software_factory/config.py

@@ -1,15 +1,219 @@
 """Configuration settings for AI Software Factory."""
 
+import json
 import os
 from typing import Optional
 from pathlib import Path
+from urllib.parse import urlparse
 from pydantic import Field
-from pydantic_settings import BaseSettings
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _normalize_service_url(value: str, default_scheme: str = "https") -> str:
+    """Normalize service URLs so host-only values still become valid absolute URLs."""
+    normalized = (value or "").strip().rstrip("/")
+    if not normalized:
+        return ""
+    if "://" not in normalized:
+        normalized = f"{default_scheme}://{normalized}"
+    parsed = urlparse(normalized)
+    if not parsed.scheme or not parsed.netloc:
+        return ""
+    return normalized
+
+
+EDITABLE_LLM_PROMPTS: dict[str, dict[str, str]] = {
+    'LLM_GUARDRAIL_PROMPT': {
+        'label': 'Global Guardrails',
+        'category': 'guardrail',
+        'description': 'Applied to every outbound external LLM call.',
+    },
+    'LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT': {
+        'label': 'Request Interpretation Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains project routing and continuation selection.',
+    },
+    'LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT': {
+        'label': 'Change Summary Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains factual delivery summaries.',
+    },
+    'LLM_PROJECT_NAMING_GUARDRAIL_PROMPT': {
+        'label': 'Project Naming Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains project display names and repo slugs.',
+    },
+    'LLM_PROJECT_NAMING_SYSTEM_PROMPT': {
+        'label': 'Project Naming System Prompt',
+        'category': 'system_prompt',
+        'description': 'Guides the dedicated new-project naming stage.',
+    },
+    'LLM_PROJECT_ID_GUARDRAIL_PROMPT': {
+        'label': 'Project ID Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains stable project id generation.',
+    },
+    'LLM_PROJECT_ID_SYSTEM_PROMPT': {
+        'label': 'Project ID System Prompt',
+        'category': 'system_prompt',
+        'description': 'Guides the dedicated project id naming stage.',
+    },
+}
+
+EDITABLE_RUNTIME_SETTINGS: dict[str, dict[str, str]] = {
+    'HOME_ASSISTANT_BATTERY_ENTITY_ID': {
+        'label': 'Battery Entity ID',
+        'category': 'home_assistant',
+        'description': 'Home Assistant entity used for battery state-of-charge gating.',
+        'value_type': 'string',
+    },
+    'HOME_ASSISTANT_SURPLUS_ENTITY_ID': {
+        'label': 'Surplus Power Entity ID',
+        'category': 'home_assistant',
+        'description': 'Home Assistant entity used for export or surplus power gating.',
+        'value_type': 'string',
+    },
+    'HOME_ASSISTANT_BATTERY_FULL_THRESHOLD': {
+        'label': 'Battery Full Threshold',
+        'category': 'home_assistant',
+        'description': 'Minimum battery percentage required before queued prompts may run.',
+        'value_type': 'float',
+    },
+    'HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS': {
+        'label': 'Surplus Threshold Watts',
+        'category': 'home_assistant',
+        'description': 'Minimum surplus/export power required before queued prompts may run.',
+        'value_type': 'float',
+    },
+    'PROMPT_QUEUE_ENABLED': {
+        'label': 'Queue Telegram Prompts',
+        'category': 'prompt_queue',
+        'description': 'When enabled, Telegram prompts are queued and gated instead of processed immediately.',
+        'value_type': 'boolean',
+    },
+    'PROMPT_QUEUE_AUTO_PROCESS': {
+        'label': 'Auto Process Queue',
+        'category': 'prompt_queue',
+        'description': 'Let the background worker drain the queue automatically when the gate is open.',
+        'value_type': 'boolean',
+    },
+    'PROMPT_QUEUE_FORCE_PROCESS': {
+        'label': 'Force Queue Processing',
+        'category': 'prompt_queue',
+        'description': 'Bypass the Home Assistant energy gate for queued prompts.',
+        'value_type': 'boolean',
+    },
+    'PROMPT_QUEUE_POLL_INTERVAL_SECONDS': {
+        'label': 'Queue Poll Interval Seconds',
+        'category': 'prompt_queue',
+        'description': 'Polling interval for the background queue worker.',
+        'value_type': 'integer',
+    },
+    'PROMPT_QUEUE_MAX_BATCH_SIZE': {
+        'label': 'Queue Max Batch Size',
+        'category': 'prompt_queue',
+        'description': 'Maximum number of queued prompts processed in one batch.',
+        'value_type': 'integer',
+    },
+}
+
+
+def _get_persisted_llm_prompt_override(env_key: str) -> str | None:
+    """Load one persisted LLM prompt override from the database when available."""
+    if env_key not in EDITABLE_LLM_PROMPTS:
+        return None
+    try:
+        try:
+            from .database import get_db_sync
+            from .agents.database_manager import DatabaseManager
+        except ImportError:
+            from database import get_db_sync
+            from agents.database_manager import DatabaseManager
+
+        db = get_db_sync()
+        if db is None:
+            return None
+        try:
+            return DatabaseManager(db).get_llm_prompt_override(env_key)
+        finally:
+            db.close()
+    except Exception:
+        return None
+
+
+def _resolve_llm_prompt_value(env_key: str, fallback: str) -> str:
+    """Resolve one editable prompt from DB override first, then environment/defaults."""
+    override = _get_persisted_llm_prompt_override(env_key)
+    if override is not None:
+        return override.strip()
+    return (fallback or '').strip()
+
+
+def _get_persisted_runtime_setting_override(key: str):
+    """Load one persisted runtime-setting override from the database when available."""
+    if key not in EDITABLE_RUNTIME_SETTINGS:
+        return None
+    try:
+        try:
+            from .database import get_db_sync
+            from .agents.database_manager import DatabaseManager
+        except ImportError:
+            from database import get_db_sync
+            from agents.database_manager import DatabaseManager
+
+        db = get_db_sync()
+        if db is None:
+            return None
+        try:
+            return DatabaseManager(db).get_runtime_setting_override(key)
+        finally:
+            db.close()
+    except Exception:
+        return None
+
+
+def _coerce_runtime_setting_value(key: str, value, fallback):
+    """Coerce a persisted runtime setting override into the expected scalar type."""
+    value_type = EDITABLE_RUNTIME_SETTINGS.get(key, {}).get('value_type')
+    if value is None:
+        return fallback
+    if value_type == 'boolean':
+        if isinstance(value, bool):
+            return value
+        normalized = str(value).strip().lower()
+        if normalized in {'1', 'true', 'yes', 'on'}:
+            return True
+        if normalized in {'0', 'false', 'no', 'off'}:
+            return False
+        return bool(fallback)
+    if value_type == 'integer':
+        try:
+            return int(value)
+        except Exception:
+            return int(fallback)
+    if value_type == 'float':
+        try:
+            return float(value)
+        except Exception:
+            return float(fallback)
+    return str(value).strip()
+
+
+def _resolve_runtime_setting_value(key: str, fallback):
+    """Resolve one editable runtime setting from DB override first, then environment/defaults."""
+    override = _get_persisted_runtime_setting_override(key)
+    return _coerce_runtime_setting_value(key, override, fallback)
 
 
 class Settings(BaseSettings):
     """Application settings loaded from environment variables."""
 
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
     # Server settings
     HOST: str = "0.0.0.0"
     PORT: int = 8000
@@ -18,23 +222,70 @@ class Settings(BaseSettings):
     # Ollama settings computed from environment
     OLLAMA_URL: str = "http://ollama:11434"
     OLLAMA_MODEL: str = "llama3"
+    LLM_GUARDRAIL_PROMPT: str = (
+        "You are operating inside AI Software Factory. Follow the requested schema exactly, "
+        "treat provided tool outputs as authoritative, and do not invent repositories, issues, pull requests, or delivery facts."
+    )
+    LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT: str = (
+        "For routing and request interpretation: never select archived projects, prefer tracked project IDs from tool outputs, and only reference issues that are explicit in the prompt or available tool data."
+    )
+    LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT: str = (
+        "For summaries: only describe facts present in the provided context and tool outputs. Never claim a repository, commit, or pull request exists unless it is present in the supplied data."
+    )
+    LLM_PROJECT_NAMING_GUARDRAIL_PROMPT: str = (
+        "For project naming: prefer clear, product-like names and repository slugs that match the user's concrete deliverable. Avoid abstract or instructional words such as purpose, project, system, app, tool, platform, solution, new, create, or test unless the request truly centers on that exact noun. Base the name on the actual artifact or workflow being built, and avoid copying sentence fragments from the prompt. Avoid reusing tracked project identities unless the request is clearly asking for an existing project."
+    )
+    LLM_PROJECT_NAMING_SYSTEM_PROMPT: str = (
+        "You name newly requested software projects. Return only JSON with keys project_name, repo_name, and rationale. Project names should be concise human-readable titles based on the real product, artifact, or workflow being created. Repo names should be lowercase kebab-case slugs derived from that title. Never return generic names like purpose, project, system, app, tool, platform, solution, harness, or test by themselves, and never return a repo_name that is a copied sentence fragment from the prompt. Prefer 2 to 4 specific words when possible."
+    )
+    LLM_PROJECT_ID_GUARDRAIL_PROMPT: str = (
+        "For project ids: produce short stable slugs for newly created projects. Avoid collisions with known project ids and keep ids lowercase with hyphens."
+    )
+    LLM_PROJECT_ID_SYSTEM_PROMPT: str = (
+        "You derive stable project ids for new projects. Return only JSON with keys project_id and rationale. project_id must be a short lowercase kebab-case slug without spaces."
+    )
+    LLM_TOOL_ALLOWLIST: str = "gitea_project_catalog,gitea_project_state,gitea_project_issues,gitea_pull_requests"
+    LLM_TOOL_CONTEXT_LIMIT: int = 5
+    LLM_LIVE_TOOL_ALLOWLIST: str = "gitea_lookup_issue,gitea_lookup_pull_request"
+    LLM_LIVE_TOOL_STAGE_ALLOWLIST: str = "request_interpretation,change_summary"
+    LLM_LIVE_TOOL_STAGE_TOOL_MAP: str = ""
+    LLM_MAX_TOOL_CALL_ROUNDS: int = 1
 
     # Gitea settings
     GITEA_URL: str = "https://gitea.yourserver.com"
     GITEA_TOKEN: str = ""
     GITEA_OWNER: str = "ai-software-factory"
-    GITEA_REPO: str = "ai-software-factory"
+    GITEA_REPO: str = ""
 
     # n8n settings
     N8N_WEBHOOK_URL: str = ""
     N8N_API_URL: str = ""
+    N8N_API_KEY: str = ""
+    N8N_TELEGRAM_CREDENTIAL_NAME: str = "AI Software Factory Telegram"
     N8N_USER: str = ""
     N8N_PASSWORD: str = ""
 
+    # Runtime integration settings
+    BACKEND_PUBLIC_URL: str = "http://localhost:8000"
+    PROJECTS_ROOT: str = ""
+
     # Telegram settings
     TELEGRAM_BOT_TOKEN: str = ""
     TELEGRAM_CHAT_ID: str = ""
 
+    # Home Assistant and prompt queue settings
+    HOME_ASSISTANT_URL: str = ""
+    HOME_ASSISTANT_TOKEN: str = ""
+    HOME_ASSISTANT_BATTERY_ENTITY_ID: str = ""
+    HOME_ASSISTANT_SURPLUS_ENTITY_ID: str = ""
+    HOME_ASSISTANT_BATTERY_FULL_THRESHOLD: float = 95.0
+    HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS: float = 100.0
+    PROMPT_QUEUE_ENABLED: bool = False
+    PROMPT_QUEUE_AUTO_PROCESS: bool = True
+    PROMPT_QUEUE_FORCE_PROCESS: bool = False
+    PROMPT_QUEUE_POLL_INTERVAL_SECONDS: int = 60
+    PROMPT_QUEUE_MAX_BATCH_SIZE: int = 1
+
     # PostgreSQL settings
     POSTGRES_HOST: str = "localhost"
     POSTGRES_PORT: int = 5432
@@ -54,6 +305,32 @@ class Settings(BaseSettings):
     DB_POOL_RECYCLE: int = 3600
     DB_POOL_TIMEOUT: int = 30
 
+    @property
+    def postgres_url(self) -> str:
+        """Get PostgreSQL URL with trimmed whitespace."""
+        return (self.POSTGRES_URL or "").strip()
+
+    @property
+    def postgres_env_configured(self) -> bool:
+        """Whether PostgreSQL was explicitly configured via environment variables."""
+        if self.postgres_url:
+            return True
+        postgres_env_keys = (
+            "POSTGRES_HOST",
+            "POSTGRES_PORT",
+            "POSTGRES_USER",
+            "POSTGRES_PASSWORD",
+            "POSTGRES_DB",
+        )
+        return any(bool(os.environ.get(key, "").strip()) for key in postgres_env_keys)
+
+    @property
+    def use_sqlite(self) -> bool:
+        """Whether SQLite should be used as the active database backend."""
+        if not self.USE_SQLITE:
+            return False
+        return not self.postgres_env_configured
+
     @property
     def pool(self) -> dict:
         """Get database pool configuration."""
@@ -67,8 +344,10 @@ class Settings(BaseSettings):
     @property
     def database_url(self) -> str:
         """Get database connection URL."""
-        if self.USE_SQLITE:
+        if self.use_sqlite:
             return f"sqlite:///{self.SQLITE_DB_PATH}"
+        if self.postgres_url:
+            return self.postgres_url
         return (
             f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
             f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
@@ -77,8 +356,10 @@ class Settings(BaseSettings):
     @property
     def test_database_url(self) -> str:
         """Get test database connection URL."""
-        if self.USE_SQLITE:
+        if self.use_sqlite:
             return f"sqlite:///{self.SQLITE_DB_PATH}"
+        if self.postgres_url:
+            return self.postgres_url
         return (
             f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
             f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_TEST_DB}"
@@ -89,20 +370,178 @@ class Settings(BaseSettings):
         """Get Ollama URL with trimmed whitespace."""
         return self.OLLAMA_URL.strip()
 
+    @property
+    def llm_guardrail_prompt(self) -> str:
+        """Get the global guardrail prompt used for all external LLM calls."""
+        return _resolve_llm_prompt_value('LLM_GUARDRAIL_PROMPT', self.LLM_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_request_interpreter_guardrail_prompt(self) -> str:
+        """Get the request-interpretation specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT', self.LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_change_summary_guardrail_prompt(self) -> str:
+        """Get the change-summary specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT', self.LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_project_naming_guardrail_prompt(self) -> str:
+        """Get the project-naming specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_NAMING_GUARDRAIL_PROMPT', self.LLM_PROJECT_NAMING_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_project_naming_system_prompt(self) -> str:
+        """Get the project-naming system prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_NAMING_SYSTEM_PROMPT', self.LLM_PROJECT_NAMING_SYSTEM_PROMPT)
+
+    @property
+    def llm_project_id_guardrail_prompt(self) -> str:
+        """Get the project-id naming specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_ID_GUARDRAIL_PROMPT', self.LLM_PROJECT_ID_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_project_id_system_prompt(self) -> str:
+        """Get the project-id naming system prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_ID_SYSTEM_PROMPT', self.LLM_PROJECT_ID_SYSTEM_PROMPT)
+
+    @property
+    def editable_llm_prompts(self) -> list[dict[str, str]]:
+        """Return metadata for all LLM prompts that may be persisted and edited from the UI."""
+        prompts = []
+        for env_key, metadata in EDITABLE_LLM_PROMPTS.items():
+            prompts.append(
+                {
+                    'key': env_key,
+                    'label': metadata['label'],
+                    'category': metadata['category'],
+                    'description': metadata['description'],
+                    'default_value': (getattr(self, env_key, '') or '').strip(),
+                    'value': _resolve_llm_prompt_value(env_key, getattr(self, env_key, '')),
+                }
+            )
+        return prompts
+
+    @property
+    def editable_runtime_settings(self) -> list[dict]:
+        """Return metadata for all DB-editable runtime settings."""
+        items = []
+        for key, metadata in EDITABLE_RUNTIME_SETTINGS.items():
+            default_value = getattr(self, key)
+            value = _resolve_runtime_setting_value(key, default_value)
+            items.append(
+                {
+                    'key': key,
+                    'label': metadata['label'],
+                    'category': metadata['category'],
+                    'description': metadata['description'],
+                    'value_type': metadata['value_type'],
+                    'default_value': default_value,
+                    'value': value,
+                }
+            )
+        return items
+
+    @property
+    def llm_tool_allowlist(self) -> list[str]:
+        """Get the allowed LLM tool names as a normalized list."""
+        return [item.strip() for item in self.LLM_TOOL_ALLOWLIST.split(',') if item.strip()]
+
+    @property
+    def llm_tool_context_limit(self) -> int:
+        """Get the number of items to expose per mediated tool payload."""
+        return max(int(self.LLM_TOOL_CONTEXT_LIMIT), 1)
+
+    @property
+    def llm_live_tool_allowlist(self) -> list[str]:
+        """Get the allowed live tool-call names for model-driven lookup requests."""
+        return [item.strip() for item in self.LLM_LIVE_TOOL_ALLOWLIST.split(',') if item.strip()]
+
+    @property
+    def llm_live_tool_stage_allowlist(self) -> list[str]:
+        """Get the LLM stages where live tool requests are enabled."""
+        return [item.strip() for item in self.LLM_LIVE_TOOL_STAGE_ALLOWLIST.split(',') if item.strip()]
+
+    @property
+    def llm_live_tool_stage_tool_map(self) -> dict[str, list[str]]:
+        """Get an optional per-stage live tool map that overrides the simple stage allowlist."""
+        raw = (self.LLM_LIVE_TOOL_STAGE_TOOL_MAP or '').strip()
+        if not raw:
+            return {}
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            return {}
+        if not isinstance(parsed, dict):
+            return {}
+        allowed_tools = set(self.llm_live_tool_allowlist)
+        normalized: dict[str, list[str]] = {}
+        for stage, tools in parsed.items():
+            if not isinstance(stage, str):
+                continue
+            if not isinstance(tools, list):
+                continue
+            normalized[stage.strip()] = [str(tool).strip() for tool in tools if str(tool).strip() in allowed_tools]
+        return normalized
+
+    def llm_live_tools_for_stage(self, stage: str) -> list[str]:
+        """Return live tools enabled for a specific LLM stage."""
+        stage_map = self.llm_live_tool_stage_tool_map
+        if stage_map:
+            return stage_map.get(stage, [])
+        if stage not in set(self.llm_live_tool_stage_allowlist):
+            return []
+        return self.llm_live_tool_allowlist
+
+    @property
+    def llm_max_tool_call_rounds(self) -> int:
+        """Get the maximum number of model-driven live tool-call rounds per LLM request."""
+        return max(int(self.LLM_MAX_TOOL_CALL_ROUNDS), 0)
+
     @property
     def gitea_url(self) -> str:
         """Get Gitea URL with trimmed whitespace."""
-        return self.GITEA_URL.strip()
+        return _normalize_service_url(self.GITEA_URL)
 
     @property
     def gitea_token(self) -> str:
         """Get Gitea token with trimmed whitespace."""
         return self.GITEA_TOKEN.strip()
 
+    @property
+    def gitea_owner(self) -> str:
+        """Get Gitea owner/organization with trimmed whitespace."""
+        return self.GITEA_OWNER.strip()
+
+    @property
+    def gitea_repo(self) -> str:
+        """Get the optional fixed Gitea repository name with trimmed whitespace."""
+        return self.GITEA_REPO.strip()
+
+    @property
+    def use_project_repositories(self) -> bool:
+        """Whether the service should create one repository per generated project."""
+        return not bool(self.gitea_repo)
+
     @property
     def n8n_webhook_url(self) -> str:
         """Get n8n webhook URL with trimmed whitespace."""
-        return self.N8N_WEBHOOK_URL.strip()
+        return _normalize_service_url(self.N8N_WEBHOOK_URL, default_scheme="http")
+
+    @property
+    def n8n_api_url(self) -> str:
+        """Get n8n API URL with trimmed whitespace."""
+        return _normalize_service_url(self.N8N_API_URL, default_scheme="http")
+
+    @property
+    def n8n_api_key(self) -> str:
+        """Get n8n API key with trimmed whitespace."""
+        return self.N8N_API_KEY.strip()
+
+    @property
+    def n8n_telegram_credential_name(self) -> str:
+        """Get the preferred n8n Telegram credential name."""
+        return self.N8N_TELEGRAM_CREDENTIAL_NAME.strip() or "AI Software Factory Telegram"
 
     @property
     def telegram_bot_token(self) -> str:
@@ -114,6 +553,73 @@ class Settings(BaseSettings):
         """Get Telegram chat ID with trimmed whitespace."""
         return self.TELEGRAM_CHAT_ID.strip()
 
+    @property
+    def backend_public_url(self) -> str:
+        """Get backend public URL with trimmed whitespace."""
+        return _normalize_service_url(self.BACKEND_PUBLIC_URL, default_scheme="http")
+
+    @property
+    def home_assistant_url(self) -> str:
+        """Get Home Assistant URL with trimmed whitespace."""
+        return _normalize_service_url(self.HOME_ASSISTANT_URL, default_scheme="http")
+
+    @property
+    def home_assistant_token(self) -> str:
+        """Get Home Assistant token with trimmed whitespace."""
+        return self.HOME_ASSISTANT_TOKEN.strip()
+
+    @property
+    def home_assistant_battery_entity_id(self) -> str:
+        """Get the Home Assistant battery state entity id."""
+        return str(_resolve_runtime_setting_value('HOME_ASSISTANT_BATTERY_ENTITY_ID', self.HOME_ASSISTANT_BATTERY_ENTITY_ID)).strip()
+
+    @property
+    def home_assistant_surplus_entity_id(self) -> str:
+        """Get the Home Assistant surplus power entity id."""
+        return str(_resolve_runtime_setting_value('HOME_ASSISTANT_SURPLUS_ENTITY_ID', self.HOME_ASSISTANT_SURPLUS_ENTITY_ID)).strip()
+
+    @property
+    def home_assistant_battery_full_threshold(self) -> float:
+        """Get the minimum battery SoC percentage for queue processing."""
+        return float(_resolve_runtime_setting_value('HOME_ASSISTANT_BATTERY_FULL_THRESHOLD', self.HOME_ASSISTANT_BATTERY_FULL_THRESHOLD))
+
+    @property
+    def home_assistant_surplus_threshold_watts(self) -> float:
+        """Get the minimum export/surplus power threshold for queue processing."""
+        return float(_resolve_runtime_setting_value('HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS', self.HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS))
+
+    @property
+    def prompt_queue_enabled(self) -> bool:
+        """Whether Telegram prompts should be queued instead of processed immediately."""
+        return bool(_resolve_runtime_setting_value('PROMPT_QUEUE_ENABLED', self.PROMPT_QUEUE_ENABLED))
+
+    @property
+    def prompt_queue_auto_process(self) -> bool:
+        """Whether the background worker should automatically process queued prompts."""
+        return bool(_resolve_runtime_setting_value('PROMPT_QUEUE_AUTO_PROCESS', self.PROMPT_QUEUE_AUTO_PROCESS))
+
+    @property
+    def prompt_queue_force_process(self) -> bool:
+        """Whether queued prompts should bypass the Home Assistant energy gate."""
+        return bool(_resolve_runtime_setting_value('PROMPT_QUEUE_FORCE_PROCESS', self.PROMPT_QUEUE_FORCE_PROCESS))
+
+    @property
+    def prompt_queue_poll_interval_seconds(self) -> int:
+        """Get the queue polling interval for background processing."""
+        return max(int(_resolve_runtime_setting_value('PROMPT_QUEUE_POLL_INTERVAL_SECONDS', self.PROMPT_QUEUE_POLL_INTERVAL_SECONDS)), 5)
+
+    @property
+    def prompt_queue_max_batch_size(self) -> int:
+        """Get the maximum number of queued prompts to process in one batch."""
+        return max(int(_resolve_runtime_setting_value('PROMPT_QUEUE_MAX_BATCH_SIZE', self.PROMPT_QUEUE_MAX_BATCH_SIZE)), 1)
+
+    @property
+    def projects_root(self) -> Path:
+        """Get the root directory for generated project artifacts."""
+        if self.PROJECTS_ROOT.strip():
+            return Path(self.PROJECTS_ROOT).expanduser().resolve()
+        return Path(__file__).resolve().parent.parent / "test-project"
+
     @property
     def postgres_host(self) -> str:
         """Get PostgreSQL host."""
@@ -144,11 +650,5 @@ class Settings(BaseSettings):
         """Get test PostgreSQL database name."""
         return self.POSTGRES_TEST_DB.strip()
 
-    class Config:
-        env_file = ".env"
-        env_file_encoding = "utf-8"
-        extra = "ignore"
-
-
 # Create instance for module-level access
 settings = Settings()

ai_software_factory/database.py

@@ -1,16 +1,50 @@
 """Database connection and session management."""
 
-from sqlalchemy import create_engine, event
+from collections.abc import Generator
-from sqlalchemy.orm import sessionmaker, Session
+from pathlib import Path
+from urllib.parse import urlparse
+
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import create_engine, event, text
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+try:
+    from .config import settings
+    from .models import Base
+except ImportError:
     from config import settings
     from models import Base
 
 
-def get_engine() -> create_engine:
+def get_database_runtime_summary() -> dict[str, str]:
+    """Return a human-readable summary of the effective database backend."""
+    if settings.use_sqlite:
+        db_path = str(Path(settings.SQLITE_DB_PATH or "/tmp/ai_software_factory_test.db").expanduser().resolve())
+        return {
+            "backend": "sqlite",
+            "target": db_path,
+            "database": db_path,
+        }
+
+    parsed = urlparse(settings.database_url)
+    database_name = parsed.path.lstrip("/") or "unknown"
+    host = parsed.hostname or "unknown-host"
+    port = str(parsed.port or 5432)
+    return {
+        "backend": parsed.scheme.split("+", 1)[0] or "postgresql",
+        "target": f"{host}:{port}/{database_name}",
+        "database": database_name,
+    }
+
+
+def get_engine() -> Engine:
     """Create and return SQLAlchemy engine with connection pooling."""
     # Use SQLite for tests, PostgreSQL for production
-    if settings.USE_SQLITE:
+    if settings.use_sqlite:
         db_path = settings.SQLITE_DB_PATH or "/tmp/ai_software_factory_test.db"
+        Path(db_path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
         db_url = f"sqlite:///{db_path}"
         # SQLite-specific configuration - no pooling for SQLite
         engine = create_engine(
@@ -19,7 +53,7 @@ def get_engine() -> create_engine:
             echo=settings.LOG_LEVEL == "DEBUG"
         )
     else:
-        db_url = settings.POSTGRES_URL or settings.database_url
+        db_url = settings.database_url
         # PostgreSQL-specific configuration
         engine = create_engine(
             db_url,
@@ -31,7 +65,7 @@ def get_engine() -> create_engine:
         )
     
     # Event listener for connection checkout (PostgreSQL only)
-    if not settings.USE_SQLITE:
+    if not settings.use_sqlite:
         @event.listens_for(engine, "checkout")
         def receive_checkout(dbapi_connection, connection_record, connection_proxy):
             """Log connection checkout for audit purposes."""
@@ -47,12 +81,11 @@ def get_engine() -> create_engine:
     return engine
 
 
-def get_session() -> Session:
+def get_session() -> Generator[Session, None, None]:
-    """Create and return database session factory."""
+    """Yield a managed database session."""
     engine = get_engine()
     SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
-    def session_factory() -> Session:
     session = SessionLocal()
     try:
         yield session
@@ -63,19 +96,10 @@ def get_session() -> Session:
     finally:
         session.close()
 
-    return session_factory
 
-
+def get_db() -> Generator[Session, None, None]:
-def get_db() -> Session:
     """Dependency for FastAPI routes that need database access."""
-    engine = get_engine()
+    yield from get_session()
-    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
-    
-    session = SessionLocal()
-    try:
-        yield session
-    finally:
-        session.close()
 
 
 def get_db_sync() -> Session:
@@ -92,43 +116,115 @@ def get_db_session() -> Session:
     return session
 
 
-def init_db() -> None:
+def get_alembic_config(database_url: str | None = None) -> Config:
-    """Initialize database tables."""
+    """Return an Alembic config bound to the active database URL."""
+    package_root = Path(__file__).resolve().parent
+    alembic_ini = package_root / "alembic.ini"
+    config = Config(str(alembic_ini))
+    config.set_main_option("script_location", str(package_root / "alembic"))
+    config.set_main_option("sqlalchemy.url", database_url or settings.database_url)
+    return config
+
+
+def run_migrations(database_url: str | None = None) -> dict:
+    """Apply Alembic migrations to the configured database."""
+    try:
+        config = get_alembic_config(database_url)
+        command.upgrade(config, "head")
+        return {"status": "success", "message": "Database migrations applied."}
+    except Exception as exc:
+        return {"status": "error", "message": str(exc)}
+
+
+def init_db() -> dict:
+    """Initialize database tables and database if needed."""
+    if settings.use_sqlite:
+        result = run_migrations()
+        if result["status"] == "success":
+            print("SQLite database migrations applied successfully.")
+            return {"status": "success", "message": "SQLite database initialized via migrations."}
         engine = get_engine()
+        try:
             Base.metadata.create_all(bind=engine)
-    print("Database tables created successfully.")
+            print("SQLite database tables created successfully.")
+            return {"status": "success", "message": "SQLite database initialized with metadata fallback."}
+        except Exception as e:
+            print(f"Error initializing SQLite database: {str(e)}")
+            return {'status': 'error', 'message': f'Error: {str(e)}'}
+    else:
+        # PostgreSQL
+        db_url = settings.database_url
+        db_name = db_url.split('/')[-1] if '/' in db_url else 'ai_software_factory'
+        
+        try:
+            # Create engine to check/create database
+            engine = create_engine(db_url)
+            
+            # Try to create database if it doesn't exist
+            try:
+                with engine.connect() as conn:
+                    # Check if database exists
+                    result = conn.execute(text(f"SELECT 1 FROM {db_name} WHERE 1=0"))
+                    # If no error, database exists
+                    conn.commit()
+                    print(f"PostgreSQL database '{db_name}' already exists.")
+            except Exception as e:
+                # Database doesn't exist or has different error - try to create it
+                error_msg = str(e).lower()
+                # Only create if it's a relation does not exist error or similar
+                if "does not exist" in error_msg or "database" in error_msg:
+                    try:
+                        conn = engine.connect()
+                        conn.execute(text(f"CREATE DATABASE {db_name}"))
+                        conn.commit()
+                        print(f"PostgreSQL database '{db_name}' created.")
+                    except Exception as db_error:
+                        print(f"Could not create database: {str(db_error)}")
+                        # Try to connect anyway - maybe using existing db name
+                        engine = create_engine(db_url.replace(f'/{db_name}', '/postgres'))
+                        with engine.connect() as conn:
+                            # Just create tables in postgres database for now
+                            print(f"Using existing 'postgres' database.")
+
+            migration_result = run_migrations(db_url)
+            if migration_result["status"] == "success":
+                print(f"PostgreSQL database '{db_name}' migrations applied successfully.")
+                return {'status': 'success', 'message': f'PostgreSQL database "{db_name}" initialized via migrations.'}
+
+            Base.metadata.create_all(bind=engine)
+            print(f"PostgreSQL database '{db_name}' tables created successfully.")
+            return {'status': 'success', 'message': f'PostgreSQL database "{db_name}" initialized with metadata fallback.'}
+        
+        except Exception as e:
+            print(f"Error initializing PostgreSQL database: {str(e)}")
+            return {'status': 'error', 'message': f'Error: {str(e)}'}
 
 
-def drop_db() -> None:
+def drop_db() -> dict:
     """Drop all database tables (use with caution!)."""
+    if settings.use_sqlite:
         engine = get_engine()
+        try:
             Base.metadata.drop_all(bind=engine)
-    print("Database tables dropped successfully.")
+            print("SQLite database tables dropped successfully.")
+            return {'status': 'success', 'message': 'SQLite tables dropped.'}
+        except Exception as e:
+            print(f"Error dropping SQLite tables: {str(e)}")
+            return {'status': 'error', 'message': str(e)}
+    else:
+        db_url = settings.database_url
+        db_name = db_url.split('/')[-1] if '/' in db_url else 'ai_software_factory'
+        
+        try:
+            engine = create_engine(db_url)
+            Base.metadata.drop_all(bind=engine)
+            print(f"PostgreSQL database '{db_name}' tables dropped successfully.")
+            return {'status': 'success', 'message': f'PostgreSQL "{db_name}" tables dropped.'}
+        except Exception as e:
+            print(f"Error dropping PostgreSQL tables: {str(e)}")
+            return {'status': 'error', 'message': str(e)}
 
 
 def create_migration_script() -> str:
     """Generate a migration script for database schema changes."""
-    return '''-- Migration script for AI Software Factory database
+    return """See ai_software_factory/alembic/versions for managed schema migrations."""
--- Generated automatically - review before applying
-
--- Add new columns to existing tables if needed
--- This is a placeholder for future migrations
-
--- Example: Add audit_trail_index for better query performance
-CREATE INDEX IF NOT EXISTS idx_audit_trail_timestamp ON audit_trail(timestamp);
-CREATE INDEX IF NOT EXISTS idx_audit_trail_action ON audit_trail(action);
-CREATE INDEX IF NOT EXISTS idx_audit_trail_project ON audit_trail(project_id);
-
--- Example: Add user_actions_index for better query performance
-CREATE INDEX IF NOT EXISTS idx_user_actions_timestamp ON user_actions(timestamp);
-CREATE INDEX IF NOT EXISTS idx_user_actions_actor ON user_actions(actor_type, actor_name);
-CREATE INDEX IF NOT EXISTS idx_user_actions_history ON user_actions(history_id);
-
--- Example: Add project_logs_index for better query performance
-CREATE INDEX IF NOT EXISTS idx_project_logs_timestamp ON project_logs(timestamp);
-CREATE INDEX IF NOT EXISTS idx_project_logs_level ON project_logs(log_level);
-
--- Example: Add system_logs_index for better query performance
-CREATE INDEX IF NOT EXISTS idx_system_logs_timestamp ON system_logs(timestamp);
-CREATE INDEX IF NOT EXISTS idx_system_logs_component ON system_logs(component);
-'''

ai_software_factory/frontend.py

@@ -5,9 +5,14 @@ The dashboard shown is from dashboard_ui.py with real-time database data.
 """
 
 from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
 
 from nicegui import app, ui
-from dashboard_ui import create_dashboard
+
+try:
+    from .dashboard_ui import create_dashboard, create_health_page
+except ImportError:
+    from dashboard_ui import create_dashboard, create_health_page
 
 
 def init(fastapi_app: FastAPI, storage_secret: str = 'Secr2t!') -> None:
@@ -18,14 +23,30 @@ def init(fastapi_app: FastAPI, storage_secret: str = 'Secr2t!') -> None:
         storage_secret: Optional secret for persistent user storage.
     """
     
-    @ui.page('/show')
+    def render_dashboard_page() -> None:
-    def show():
+        ui.page_title('AI Software Factory')
         create_dashboard()
 
         # NOTE dark mode will be persistent for each user across tabs and server restarts
         ui.dark_mode().bind_value(app.storage.user, 'dark_mode')
         ui.checkbox('dark mode').bind_value(app.storage.user, 'dark_mode')
 
+    @ui.page('/')
+    def home() -> None:
+        render_dashboard_page()
+
+    @ui.page('/show')
+    def show() -> None:
+        render_dashboard_page()
+
+    @ui.page('/health-ui')
+    def health_ui() -> None:
+        create_health_page()
+
+    @fastapi_app.get('/dashboard', include_in_schema=False)
+    def dashboard_redirect() -> RedirectResponse:
+        return RedirectResponse(url='/', status_code=307)
+    
     ui.run_with(
         fastapi_app,
         storage_secret=storage_secret,  # NOTE setting a secret is optional but allows for persistent storage per user

ai_software_factory/hello_world.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-echo "Hello world"

ai_software_factory/models.py

@@ -10,6 +10,9 @@ from sqlalchemy import (
 )
 from sqlalchemy.orm import relationship, declarative_base
 
+try:
+    from .config import settings
+except ImportError:
     from config import settings
 
 Base = declarative_base()
@@ -52,6 +55,7 @@ class ProjectHistory(Base):
     ui_snapshots = relationship("UISnapshot", back_populates="project_history", cascade="all, delete-orphan")
     pull_requests = relationship("PullRequest", back_populates="project_history", cascade="all, delete-orphan")
     pull_request_data = relationship("PullRequestData", back_populates="project_history", cascade="all, delete-orphan")
+    prompt_code_links = relationship("PromptCodeLink", back_populates="project_history", cascade="all, delete-orphan")
 
 
 class ProjectLog(Base):
@@ -145,6 +149,22 @@ class AuditTrail(Base):
     metadata_json = Column(JSON, nullable=True)
 
 
+class PromptCodeLink(Base):
+    """Explicit lineage between a prompt event and a resulting code change."""
+    __tablename__ = "prompt_code_links"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=False)
+    project_id = Column(String(255), nullable=False)
+    prompt_audit_id = Column(Integer, nullable=False)
+    code_change_audit_id = Column(Integer, nullable=False)
+    file_path = Column(String(500), nullable=True)
+    change_type = Column(String(50), nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    project_history = relationship("ProjectHistory", back_populates="prompt_code_links")
+
+
 class UserAction(Base):
     """User action audit entries."""
     __tablename__ = "user_actions"

ai_software_factory/requirements.txt

@@ -16,3 +16,6 @@ flake8==6.1.0
 mypy==1.7.1
 httpx==0.25.2
 nicegui==3.9.0
+aiohttp>=3.9.0
+pytest-asyncio>=0.23.0
+alembic>=1.14.0

ai_software_factory/templates/dashboard.html

@@ -1,385 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>AI Software Factory Dashboard</title>
-    <style>
-        * {
-            margin: 0;
-            padding: 0;
-            box-sizing: border-box;
-        }
-
-        body {
-            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
-            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
-            min-height: 100vh;
-            color: #fff;
-            padding: 20px;
-        }
-
-        .dashboard {
-            max-width: 1200px;
-            margin: 0 auto;
-        }
-
-        .header {
-            text-align: center;
-            padding: 30px;
-            background: rgba(255, 255, 255, 0.05);
-            border-radius: 15px;
-            margin-bottom: 20px;
-            border: 1px solid rgba(255, 255, 255, 0.1);
-        }
-
-        .header h1 {
-            font-size: 2.5em;
-            margin-bottom: 10px;
-            background: linear-gradient(90deg, #00d4ff, #00ff88);
-            -webkit-background-clip: text;
-            -webkit-text-fill-color: transparent;
-            background-clip: text;
-        }
-
-        .header p {
-            color: #888;
-            font-size: 1.1em;
-        }
-
-        .stats-grid {
-            display: grid;
-            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-            gap: 20px;
-            margin-bottom: 20px;
-        }
-
-        .stat-card {
-            background: rgba(255, 255, 255, 0.05);
-            border-radius: 15px;
-            padding: 25px;
-            border: 1px solid rgba(255, 255, 255, 0.1);
-            text-align: center;
-        }
-
-        .stat-card h3 {
-            font-size: 0.9em;
-            color: #888;
-            margin-bottom: 10px;
-            text-transform: uppercase;
-            letter-spacing: 1px;
-        }
-
-        .stat-card .value {
-            font-size: 2.5em;
-            font-weight: bold;
-            color: #00d4ff;
-        }
-
-        .stat-card.project .value { color: #00ff88; }
-        .stat-card.active .value { color: #ff6b6b; }
-        .stat-card.code .value { color: #ffd93d; }
-
-        .status-panel {
-            background: rgba(255, 255, 255, 0.05);
-            border-radius: 15px;
-            padding: 25px;
-            margin-bottom: 20px;
-            border: 1px solid rgba(255, 255, 255, 0.1);
-        }
-
-        .status-panel h2 {
-            font-size: 1.3em;
-            margin-bottom: 15px;
-            color: #00d4ff;
-        }
-
-        .status-bar {
-            height: 20px;
-            background: #2a2a4a;
-            border-radius: 10px;
-            overflow: hidden;
-            margin-bottom: 10px;
-        }
-
-        .status-fill {
-            height: 100%;
-            background: linear-gradient(90deg, #00d4ff, #00ff88);
-            border-radius: 10px;
-            transition: width 0.5s ease;
-        }
-
-        .message {
-            padding: 10px;
-            background: rgba(0, 212, 255, 0.1);
-            border-radius: 8px;
-            border-left: 4px solid #00d4ff;
-        }
-
-        .projects-section {
-            background: rgba(255, 255, 255, 0.05);
-            border-radius: 15px;
-            padding: 25px;
-            margin-bottom: 20px;
-            border: 1px solid rgba(255, 255, 255, 0.1);
-        }
-
-        .projects-section h2 {
-            font-size: 1.3em;
-            margin-bottom: 15px;
-            color: #00ff88;
-        }
-
-        .projects-list {
-            display: flex;
-            flex-wrap: wrap;
-            gap: 15px;
-        }
-
-        .project-item {
-            background: rgba(0, 255, 136, 0.1);
-            padding: 15px 20px;
-            border-radius: 10px;
-            border: 1px solid rgba(0, 255, 136, 0.3);
-            font-size: 0.9em;
-        }
-
-        .project-item.active {
-            background: rgba(255, 107, 107, 0.1);
-            border-color: rgba(255, 107, 107, 0.3);
-        }
-
-        .audit-section {
-            background: rgba(255, 255, 255, 0.05);
-            border-radius: 15px;
-            padding: 25px;
-            margin-bottom: 20px;
-            border: 1px solid rgba(255, 255, 255, 0.1);
-        }
-
-        .audit-section h2 {
-            font-size: 1.3em;
-            margin-bottom: 15px;
-            color: #ffd93d;
-        }
-
-        .audit-table {
-            width: 100%;
-            border-collapse: collapse;
-            margin-top: 10px;
-        }
-
-        .audit-table th, .audit-table td {
-            padding: 12px;
-            text-align: left;
-            border-bottom: 1px solid rgba(255, 255, 255, 0.1);
-        }
-
-        .audit-table th {
-            color: #888;
-            font-weight: 600;
-            font-size: 0.85em;
-        }
-
-        .audit-table td {
-            font-size: 0.9em;
-        }
-
-        .audit-table .timestamp {
-            color: #666;
-            font-size: 0.8em;
-        }
-
-        .actions-panel {
-            background: rgba(255, 255, 255, 0.05);
-            border-radius: 15px;
-            padding: 25px;
-            border: 1px solid rgba(255, 255, 255, 0.1);
-            text-align: center;
-        }
-
-        .actions-panel h2 {
-            font-size: 1.3em;
-            margin-bottom: 15px;
-            color: #ff6b6b;
-        }
-
-        .actions-panel p {
-            color: #888;
-            margin-bottom: 20px;
-        }
-
-        .loading {
-            text-align: center;
-            padding: 50px;
-            color: #888;
-        }
-
-        @media (max-width: 768px) {
-            .stats-grid {
-                grid-template-columns: 1fr;
-            }
-            
-            .projects-list {
-                flex-direction: column;
-            }
-        }
-    </style>
-</head>
-<body>
-    <div class="dashboard">
-        <div class="header">
-            <h1>🚀 AI Software Factory</h1>
-            <p>Real-time Dashboard & Audit Trail Display</p>
-        </div>
-
-        <div class="stats-grid">
-            <div class="stat-card project">
-                <h3>Current Project</h3>
-                <div class="value" id="project-name">Loading...</div>
-            </div>
-            <div class="stat-card active">
-                <h3>Active Projects</h3>
-                <div class="value" id="active-projects">0</div>
-            </div>
-            <div class="stat-card code">
-                <h3>Total Projects</h3>
-                <div class="value" id="total-projects">0</div>
-            </div>
-            <div class="stat-card">
-                <h3>Status</h3>
-                <div class="value" id="status-value">Loading...</div>
-            </div>
-        </div>
-
-        <div class="status-panel">
-            <h2>📊 Current Status</h2>
-            <div class="status-bar">
-                <div class="status-fill" id="status-fill" style="width: 0%"></div>
-            </div>
-            <div class="message" id="status-message">Loading...</div>
-        </div>
-
-        <div class="projects-section">
-            <h2>📁 Active Projects</h2>
-            <div class="projects-list" id="projects-list">
-                <div class="loading">Loading projects...</div>
-            </div>
-        </div>
-
-        <div class="audit-section">
-            <h2>📜 Audit Trail</h2>
-            <table class="audit-table">
-                <thead>
-                    <tr>
-                        <th>Timestamp</th>
-                        <th>Agent</th>
-                        <th>Action</th>
-                        <th>Status</th>
-                    </tr>
-                </thead>
-                <tbody id="audit-trail-body">
-                    <tr>
-                        <td class="timestamp">Loading...</td>
-                        <td>-</td>
-                        <td>-</td>
-                        <td>-</td>
-                    </tr>
-                </tbody>
-            </table>
-        </div>
-
-        <div class="actions-panel">
-            <h2>⚙️ System Actions</h2>
-            <p id="actions-message">Dashboard is rendering successfully.</p>
-            <p style="color: #888; font-size: 0.9em;">This dashboard is powered by the AI Software Factory and displays real-time status updates, audit trails, and project information.</p>
-        </div>
-    </div>
-
-    <script>
-        // Fetch data from API
-        async function loadDashboardData() {
-            try {
-                // Load projects
-                const projectsResponse = await fetch('/projects');
-                const projectsData = await projectsResponse.json();
-                updateProjects(projectsData.projects);
-
-                // Get latest active project
-                const activeProject = projectsData.projects.find(p => p.status === 'RUNNING' || p.status === 'IN_PROGRESS');
-                
-                if (activeProject) {
-                    document.getElementById('project-name').textContent = activeProject.project_name || activeProject.project_id;
-                    updateStatusPanel(activeProject);
-                    
-                    // Load audit trail for this project
-                    const auditResponse = await fetch(`/audit/trail?limit=10`);
-                    const auditData = await auditResponse.json();
-                    updateAuditTrail(auditData.audit_trail);
-                } else {
-                    // No active project, show all projects
-                    document.getElementById('projects-list').innerHTML = projectsData.projects.map(p => 
-                        `<div class="project-item ${p.status === 'RUNNING' || p.status === 'IN_PROGRESS' ? 'active' : ''}">
-                            <strong>${p.project_name || p.project_id}</strong> • ${p.status} • ${p.progress || 0}%
-                        </div>`
-                    ).join('');
-                }
-
-            } catch (error) {
-                console.error('Error loading dashboard data:', error);
-                document.getElementById('status-message').innerHTML = 
-                    `<strong>Error:</strong> Failed to load dashboard data. Please check the console for details.`;
-            }
-        }
-
-        function updateProjects(projects) {
-            const activeProjects = projects.filter(p => p.status === 'RUNNING' || p.status === 'IN_PROGRESS' || p.status === 'COMPLETED').length;
-            document.getElementById('active-projects').textContent = activeProjects;
-            document.getElementById('total-projects').textContent = projects.length;
-        }
-
-        function updateStatusPanel(project) {
-            const progress = project.progress || 0;
-            document.getElementById('status-fill').style.width = progress + '%';
-            document.getElementById('status-message').innerHTML = 
-                `<strong>${project.message || 'Project running...'}</strong><br>` +
-                `<span style="color: #888;">Progress: ${progress}%</span>`;
-            document.getElementById('status-value').textContent = project.status;
-        }
-
-        function updateAuditTrail(auditEntries) {
-            if (auditEntries.length === 0) {
-                document.getElementById('audit-trail-body').innerHTML = 
-                    `<tr><td colspan="4" style="text-align: center; color: #888;">No audit entries yet</td></tr>`;
-                return;
-            }
-
-            const formattedEntries = auditEntries.map(entry => ({
-                ...entry,
-                timestamp: entry.timestamp ? new Date(entry.timestamp).toLocaleString() : '-'
-            }));
-
-            document.getElementById('audit-trail-body').innerHTML = formattedEntries.map(entry => `
-                <tr>
-                    <td class="timestamp">${entry.timestamp}</td>
-                    <td>${entry.actor || '-'}</td>
-                    <td>${entry.action || entry.details || '-'}</td>
-                    <td style="color: ${getStatusColor(entry.action_type || entry.status)};">${entry.action_type || entry.status || '-'}</td>
-                </tr>
-            `).join('');
-        }
-
-        function getStatusColor(status) {
-            if (!status) return '#888';
-            const upper = status.toUpperCase();
-            if (['SUCCESS', 'COMPLETED', 'FINISHED'].includes(upper)) return '#00ff88';
-            if (['IN_PROGRESS', 'RUNNING', 'PENDING'].includes(upper)) return '#00d4ff';
-            if (['ERROR', 'FAILED', 'FAILED'].includes(upper)) return '#ff6b6b';
-            return '#888';
-        }
-
-        // Load data when dashboard is ready
-        loadDashboardData();
-    </script>
-</body>
-</html>