@jaguilar87/gaia-ops 2.2.2 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ All notable changes to the CLAUDE.md orchestrator instructions are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2025-11-11
+
+### Added - Phase 0 Clarification Module
+- **NEW:** `tools/clarification/` module for intelligent ambiguity detection before routing
+  - `clarification/engine.py`: Core clarification engine (refactored from clarify_engine.py)
+  - `clarification/patterns.py`: Ambiguity detection patterns (ServiceAmbiguityPattern, NamespaceAmbiguityPattern, etc.)
+  - `clarification/workflow.py`: High-level helper functions for orchestrators (`execute_workflow()`)
+  - `clarification/__init__.py`: Clean public API
+- **Protocol G** in `agents/gaia.md`: Clarification system analysis and troubleshooting guide
+- **Rule 5.0.1** in `templates/CLAUDE.template.md`: Phase 0 implementation guide with code examples
+- **Phase 0 integration** in `/speckit.specify` command
+- **Regression tests** in `tests/integration/test_phase_0_regression.py`
+- **Clarification metrics** to Key System Metrics (target: 20-30% clarification rate)
+
+### Changed - Module Restructuring (BREAKING)
+- **BREAKING:** `clarify_engine.py` and `clarify_patterns.py` moved to `clarification/` module
+  - **Old imports:** `from clarify_engine import request_clarification`
+  - **New imports:** `from clarification import execute_workflow, request_clarification`
+- Updated `application_services` structure in project-context.json:
+  - Added `tech_stack` field (replaces `technology`)
+  - Added `namespace` field for service location
+  - **Removed** `status` field (dynamic state must be verified in real-time, not stored in SSOT)
+- Service metadata now shows only static information: `tech_stack | namespace | port`
+
+### Fixed
+- Import paths in `tests/tools/test_clarify_engine.py` updated to new module structure
+- Service metadata test updated to reflect removal of dynamic status field
+- All 20 unit tests passing with new module structure
+
+### Documentation
+- Added comprehensive Phase 0 implementation guide
+- Added troubleshooting guide for clarification system
+- Updated speckit.specify.md with Phase 0 workflow integration
+- Added Protocol G diagnostic steps in gaia.md
+
+### Migration Guide for v2.3.0
+```python
+# Before (v2.2.x)
+from clarify_engine import request_clarification, process_clarification
+
+# After (v2.3.0)
+from clarification import execute_workflow
+
+# Simple usage
+result = execute_workflow(user_prompt)
+enriched_prompt = result["enriched_prompt"]
+```
+
+## [2.2.3] - 2025-11-11
+
+### Fixed - Deterministic Project Context Location
+- **context_provider.py**
+  - Always reads `.claude/project-context/project-context.json` (no fallback to legacy paths)
+  - Removed legacy auto-detection logic and unused imports
+  - Prevents “Context file not found” errors when projects only use the new structure
+- **templates/CLAUDE.template.md**
+  - Rule 1 clarifies when to delegate vs. self-execute
+  - Rule 2 explicitly documents the `context_provider.py --context-file .claude/project-context/project-context.json …` invocation
+  - Workflow summary now references orchestration docs after the table (cleaner render)
+
+### Changed - CLI Documentation & Version Alignment
+- **README.md / README.en.md**
+  - Documented the exact `npx` commands (`npx gaia-init` / `npx @jaguilar87/gaia-ops`) and clarified installation steps
+  - Updated “Current version” badges to **2.2.3**
+- **package.json**
+  - Bumped package version to `2.2.3`
+
+### Benefits
+- ✅ No manual tweaks needed to point `context_provider.py` at the correct project context
+- ✅ CLAUDE template now tells the orchestrator exactly how to invoke the context provider
+- ✅ README instructions reflect the real CLI entry points, reducing confusion for new installs
+
 ---
 
 ## [2.2.2] - 2025-11-11
@@ -591,9 +663,9 @@ contract_keys = contracts["agents"][agent_name]["required"]  # Provider-specific
 
 **Recommended:**
 
-- Read `.claude/docs/orchestration-workflow.md` to understand full Phase 0-6 workflow
-- Review `.claude/docs/git-standards.md` for complete commit standards
-- Check `.claude/docs/agent-catalog.md` for detailed agent capabilities
+- Read `.claude/config/orchestration-workflow.md` to understand full Phase 0-6 workflow
+- Review `.claude/config/git-standards.md` for complete commit standards
+- Check `.claude/config/agent-catalog.md` for detailed agent capabilities
 
 ---
 
@@ -624,8 +696,8 @@ contract_keys = contracts["agents"][agent_name]["required"]  # Provider-specific
    - Add entry to this CHANGELOG under "Unreleased"
 
 2. **For new sections or features:**
-   - Decide if belongs in `CLAUDE.md` (core instructions) or `.claude/docs/*.md` (details)
-   - If modular doc, create/update appropriate file in `.claude/docs/`
+   - Decide if belongs in `CLAUDE.md` (core instructions) or `.claude/config/*.md` (details)
+   - If modular doc, create/update appropriate file in `.claude/config/`
    - If core instruction, update `CLAUDE.md` and add reference to modular doc
    - Increment MINOR version in frontmatter
    - Add entry to this CHANGELOG under "Unreleased"

package/README.en.md

@@ -30,7 +30,11 @@ Multi-agent orchestration system for Claude Code - DevOps automation toolkit.
 Use the built-in interactive installer to set up Gaia-Ops in any project:
 
 ```bash
-npx @jaguilar87/gaia-ops init
+# Option 1: run the binary directly via npx
+npx gaia-init
+
+# Option 2: specify the npm package explicitly
+npx @jaguilar87/gaia-ops
 ```
 
 Or if installed globally:
@@ -189,7 +193,7 @@ This package follows [Semantic Versioning](https://semver.org/):
 - **MINOR:** New features, agents, or improvements
 - **PATCH:** Bug fixes, clarifications, typos
 
-Current version: **2.2.0**
+Current version: **2.2.3**
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.
 

package/README.md

@@ -30,7 +30,11 @@ Sistema de orquestación multi-agente para Claude Code - Toolkit de automatizaci
 Usa el instalador interactivo integrado para configurar Gaia-Ops en cualquier proyecto:
 
 ```bash
-npx @jaguilar87/gaia-ops init
+# Opción 1: Ejecutar directamente con npx
+npx gaia-init
+
+# Opción 2: Si prefieres especificar el paquete completo
+npx @jaguilar87/gaia-ops
 ```
 
 O si lo instalas globalmente:
@@ -185,11 +189,11 @@ const configPath = getConfigPath('orchestration-workflow.md');
 
 Este paquete sigue [Versionamiento Semántico](https://semver.org/):
 
-- **MAJOR:** Cambios que rompen compatibilidad en el comportamiento del orquestador
-- **MINOR:** Nuevas características, agentes o mejoras
-- **PATCH:** Correcciones de bugs, clarificaciones, errores tipográficos
+    - **MAJOR:** Cambios que rompen compatibilidad en el comportamiento del orquestador
+    - **MINOR:** Nuevas características, agentes o mejoras
+    - **PATCH:** Correcciones de bugs, clarificaciones, errores tipográficos
 
-Versión actual: **2.2.0**
+    Versión actual: **2.2.3**
 
 Ver [CHANGELOG.md](./CHANGELOG.md) para el historial de versiones.
 

package/agents/gaia.md

@@ -113,6 +113,8 @@ When `npx @jaguilar87/gaia-ops init` (or `gaia-init` after a global install) run
 ### Key System Metrics (What to Track)
 
 - **Routing Accuracy:** Target 92.7% (from tests)
+- **Clarification Rate:** Target 20-30% (Phase 0 effectiveness)
+- **Clarification Effectiveness:** Routing accuracy improvement post-enrichment
 - **Context Efficiency:** 79-85% token savings (via context_provider.py)
 - **Test Coverage:** 55+ tests, 100% pass rate
 - **Production Uptime:** Track via logs/
@@ -472,6 +474,88 @@ You:
 
 **Output:** Feature RFC (Request for Comments)
 
+### Protocol G: Clarification System Analysis
+
+**Trigger:** "¿Por qué no se activó clarificación?" or "Ambiguity detection issues" or "Analyze Phase 0"
+
+**Steps:**
+1. Review clarification logs:
+   ```bash
+   cat .claude/logs/clarifications.jsonl | jq .
+   ```
+
+2. Check configuration:
+   ```bash
+   cat .claude/config/clarification_rules.json
+   jq '.global_settings' .claude/config/clarification_rules.json
+   ```
+
+3. Test detection manually:
+   ```python
+   import sys
+   sys.path.insert(0, '.claude/tools')
+   from clarification import execute_workflow, request_clarification
+
+   result = request_clarification("Check the API")
+   print(f"Needs clarification: {result['needs_clarification']}")
+   print(f"Ambiguity score: {result.get('ambiguity_score', 0)}")
+   print(f"Patterns detected: {[a['pattern'] for a in result.get('ambiguity_points', [])]}")
+   ```
+
+4. Review pattern definitions:
+   ```bash
+   cat .claude/tools/clarification/patterns.py
+   ```
+
+5. Analyze recent clarifications:
+   ```bash
+   cat .claude/logs/clarifications.jsonl | \
+     jq -r '[.timestamp, .ambiguity_score, .original_prompt] | @csv' | \
+     tail -20
+   ```
+
+6. Benchmark effectiveness:
+   - **Clarification rate:** Target 20-30%
+   - **User satisfaction:** No complaints about "too many questions"
+   - **Routing accuracy improvement:** Measure before/after enrichment
+
+7. Check module structure:
+   ```bash
+   ls -la .claude/tools/clarification/
+   # Should show: __init__.py, engine.py, patterns.py, workflow.py
+   ```
+
+**Output:** Clarification effectiveness report + tuning recommendations
+
+**Common Issues:**
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Threshold too high | Ambiguity not detected | Lower from 30 to 20 in `clarification_rules.json` |
+| Threshold too low | Too many questions | Raise from 30 to 40 |
+| Missing patterns | New ambiguous terms not caught | Add to `patterns.py` (ServiceAmbiguityPattern.keywords) |
+| Spanish keywords missing | Spanish prompts not detected | Add to keywords list in patterns |
+| Import errors | Module not found | Check symlinks to gaia-ops package |
+| No services found | Tests failing | Verify `project-context.json` has `application_services` section |
+
+**Metrics to Track:**
+
+```python
+# Calculate clarification rate
+import json
+
+with open('.claude/logs/clarifications.jsonl') as f:
+    logs = [json.loads(line) for line in f]
+
+total_requests = len(logs)
+clarified = sum(1 for log in logs if log.get('ambiguity_score', 0) > 30)
+rate = (clarified / total_requests * 100) if total_requests > 0 else 0
+
+print(f"Clarification rate: {rate:.1f}%")
+print(f"Target: 20-30%")
+print(f"Status: {'✅ Good' if 20 <= rate <= 30 else '⚠️ Needs tuning'}")
+```
+
 ## Research Guidelines (WebSearch Usage)
 
 When researching, follow this pattern:

package/commands/speckit.specify.md

@@ -31,32 +31,23 @@ Given those arguments, do this:
 
    ```python
    import sys
-   sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
-   from clarify_engine import request_clarification, process_clarification
+   sys.path.insert(0, '.claude/tools')
+   from clarification import execute_workflow
 
-   # Detect ambiguity in feature description
-   clarification_data = request_clarification(
+   # Detect and resolve ambiguity in feature description
+   result = execute_workflow(
        user_prompt=feature_description,
-       command_context={"command": "speckit.specify"}
+       command_context={"command": "speckit.specify"},
+       ask_user_question_func=AskUserQuestion  # Claude Code tool
    )
 
-   if clarification_data["needs_clarification"]:
-       # Present summary
-       print(clarification_data["summary"])
+   # Use enriched description for remaining steps
+   feature_description = result["enriched_prompt"]
 
-       # Ask questions (AskUserQuestion tool)
-       response = AskUserQuestion(**clarification_data["question_config"])
-
-       # Enrich feature description
-       result = process_clarification(
-           clarification_data["engine_instance"],
-           feature_description,
-           response["answers"],
-           clarification_data["clarification_context"]
-       )
-
-       # Use enriched description for remaining steps
-       feature_description = result["enriched_prompt"]
+   # Log clarification if it occurred
+   if result["clarification_occurred"]:
+       from clarification import get_clarification_summary
+       print(get_clarification_summary(result["clarification_data"]))
    ```
 
    **What gets clarified**:

package/config/AGENTS.md

@@ -80,7 +80,7 @@ Claude Code (Orchestrator)
 - Route user requests to specialist agents
 - Provision context via `context_provider.py`
 - Enforce approval gates for T3 operations
-- Update system SSOTs (project-context.json, tasks.md)
+- Update system SSOTs (.claude/project-context/project-context.json, tasks.md)
 - Handle simple operations directly (ad-hoc commits, queries)
 
 **Agent responsibilities:**
@@ -94,12 +94,12 @@ Claude Code (Orchestrator)
 ## Documentation Structure
 
 ```
-/home/jaguilar/aaxis/rnd/repositories/
+<project-root>/
 ├── CLAUDE.md (core orchestrator instructions, 196 lines)
 ├── AGENTS.md (this file, compatibility layer)
 ├── .claude/
 │   ├── CHANGELOG.md (version history)
-│   ├── docs/
+│   ├── config/
 │   │   ├── orchestration-workflow.md (Phase 0-6 details)
 │   │   ├── git-standards.md (commit standards)
 │   │   ├── context-contracts.md (agent context requirements)
@@ -107,8 +107,9 @@ Claude Code (Orchestrator)
 │   ├── agents/ (agent definitions)
 │   ├── tools/ (context_provider.py, agent_router.py, etc.)
 │   ├── logs/ (audit trail, metrics)
-│   └── tests/ (test suite)
-└── .claude/project-context.json (SSOT for infrastructure state)
+│   ├── tests/ (test suite)
+│   └── project-context/
+│       └── project-context.json (SSOT for infrastructure state)
 ```
 
 ---
@@ -117,7 +118,7 @@ Claude Code (Orchestrator)
 
 1. **Read CLAUDE.md** (5 min) - Understand core principles and workflow
 2. **Review agent catalog** (10 min) - See available agents and capabilities
-3. **Check project context** (5 min) - Review `.claude/project-context.json` for current infrastructure state
+3. **Check project context** (5 min) - Review `.claude/project-context/project-context.json` for current infrastructure state
 4. **Run sample workflow** (15 min) - Test orchestrator with a simple task
 
 **Sample workflow:**
@@ -145,7 +146,7 @@ See `CLAUDE.md` and `.claude/CHANGELOG.md` for contribution guidelines.
 **Key rules:**
 - All commits MUST follow Conventional Commits (enforced by `commit_validator.py`)
 - Changes to infrastructure/deployments require approval gate (Phase 4)
-- Update SSOTs after realization (project-context.json, tasks.md)
+- Update SSOTs after realization (.claude/project-context/project-context.json, tasks.md)
 
 ---
 

package/index.js

@@ -54,17 +54,6 @@ export function getCommandPath(commandName) {
   return join(PACKAGE_ROOT, 'commands', commandName);
 }
 
-/**
- * Get absolute path to documentation
- * @deprecated Use getConfigPath() instead. Documentation moved from docs/ to config/ in v2.0.0
- * @param {string} docName - Name of the doc (e.g., 'orchestration-workflow.md')
- * @returns {string} Absolute path to doc file
- */
-export function getDocPath(docName) {
-  console.warn('getDocPath() is deprecated. Use getConfigPath() instead. Documentation is now in config/ directory.');
-  return join(PACKAGE_ROOT, 'config', docName);
-}
-
 /**
  * Get absolute path to a template
  * @param {string} templateName - Name of the template (e.g., 'CLAUDE.template.md')
@@ -89,7 +78,6 @@ export default {
   getToolPath,
   getHookPath,
   getCommandPath,
-  getDocPath,
   getTemplatePath,
   getConfigPath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia-ops",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/templates/CLAUDE.template.md

@@ -1,21 +1,14 @@
-# CLAUDE.md
-
-Guidance for Claude Code orchestrator working in this repository.
-
-## Language Policy
-
-- **Technical Documentation:** All code, commits, technical documentation, and system artifacts MUST be in English.
-- **Chat Interactions:** Always respond to users in the same language used during chat conversations.
-
 ## Core Operating Principles
 
-### Rule 1.0 [P0]: Selective Delegation
-- **COMPLEX workflows** (investiogatiops, multi-step, infrastructure, deployments) → Delegate to specialist agents
-- **SIMPLE operations** (atomic commits, file edits) → Execute directly
-- **Default:** When in doubt, delegate (safer)
+### Rule 1.0 [P0]: Delegate Anything Non-Atomic
+- **Always delegate** investigations, multi-file edits, Terraform/Helm/K8s/GitOps actions, or anything needing approval / T2-T3 access.
+- **Only execute yourself** when it’s a truly atomic, low-risk step (single-file edit, log read, simple status query).
+- If you choose not to delegate, say why it is safe to keep it local.
+
+❌ Never self-execute chained workflows or infrastructure-impacting changes.
 
 ### Rule 2.0 [P0]: Context Provisioning
-- Use `context_provider.py` to build agent payload (ONLY for project agents)
+- Project agents must receive `context_provider.py --context-file .claude/project-context/project-context.json …`
 - Meta-agents receive manual context in prompt
 
 ### Rule 3.0 [P0]: Two-Phase Workflow for Infrastructure
@@ -30,13 +23,11 @@ Guidance for Claude Code orchestrator working in this repository.
 
 ## Orchestrator Workflow
 
-**See:** `.claude/config/orchestration-workflow.md` for complete details.
-
 ### Rule 5.0 [P0]: Six-Phase Workflow
 
 | Phase | Action | Tool | Mandatory |
 |-------|--------|------|-----------|
-| 0 | Clarification (if ambiguous) | `clarify_engine.py` | Conditional |
+| 0 | Clarification (if ambiguous) | `clarification` module | Conditional |
 | 1 | Route to agent | `agent_router.py` | Yes |
 | 2 | Provision context | `context_provider.py` | Yes |
 | 3 | Invoke (Planning) | `Task` tool | Yes |
@@ -44,6 +35,57 @@ Guidance for Claude Code orchestrator working in this repository.
 | 5 | Realization | `Task` tool (re-invoke) | Yes |
 | 6 | Update SSOT | Edit `project-context.json`, `tasks.md` | Yes |
 
+**See:** `.claude/config/orchestration-workflow.md` for complete details.
+
+### Rule 5.0.1 [P0]: Phase 0 Implementation
+
+**When to invoke Phase 0:**
+- User prompt contains generic terms: "the service", "the API", "the cluster"
+- User mentions "production" but project-context says "non-prod"
+- User references resource without specifying which (Redis, DB, namespace)
+- Ambiguity score > 30 (threshold configurable in `.claude/config/clarification_rules.json`)
+
+**When to skip Phase 0:**
+- User prompt is specific: "tcm-api in tcm-non-prod"
+- Read-only queries: "show me logs"
+- Simple commands: "/help", "/status"
+
+**Code Integration:**
+
+```python
+import sys
+sys.path.insert(0, '.claude/tools')
+from clarification import execute_workflow
+
+# At orchestrator entry point
+result = execute_workflow(
+    user_prompt=user_prompt,
+    command_context={"command": "general_prompt"}
+)
+
+enriched_prompt = result["enriched_prompt"]
+
+# Then proceed to Phase 1 with enriched_prompt
+# agent = route_to_agent(enriched_prompt)
+```
+
+**Manual Mode (custom UX):**
+
+```python
+from clarification import execute_workflow
+
+result = execute_workflow(user_prompt)  # No ask_user_question_func
+
+if result.get("needs_manual_questioning"):
+    # Show summary and questions to user
+    print(result["summary"])
+
+    # Get user responses with custom UI
+    # Then manually process clarification
+```
+
+**See:** `.claude/config/orchestration-workflow.md` lines 25-150 for complete Phase 0 protocol.
+
 ### Rule 5.1 [P0]: Approval Gate Enforcement
 - Phase 4 CANNOT be skipped for T3 operations
 - Phase 5 requires `validation["approved"] == True`
@@ -154,3 +196,10 @@ Guidance for Claude Code orchestrator working in this repository.
 - **Context contracts:** `.claude/config/context-contracts.md`
 - **Agent catalog:** `.claude/config/agent-catalog.md`
 - **Package source:** `@jaguilar87/gaia-ops` (npm package)
+
+## Language Policy
+
+- **Technical Documentation:** All code, commits, technical documentation, and system artifacts MUST be in English.
+- **Chat Interactions:** Always respond to users in the same language used during chat conversations.
+
+

package/tests/integration/test_phase_0_regression.py

@@ -0,0 +1,175 @@
+"""
+Phase 0 Regression Tests
+
+Regression tests for specific cases that should trigger clarification.
+These tests validate real-world scenarios where ambiguity detection is critical.
+"""
+
+import pytest
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', 'tools'))
+
+from clarification import request_clarification, execute_workflow
+
+
+def test_regression_valida_servicio_tcm():
+    """
+    Regression test for: "valida el servicio de tcm"
+
+    This SHOULD trigger clarification because:
+    1. "el servicio" is ambiguous (ServiceAmbiguityPattern)
+    2. "tcm" is not a specific service name (could be tcm-api, tcm-web, tcm-bot, tcm-jobs)
+    3. "validar" is generic (no specific action)
+
+    Expected behavior:
+    - Detect service ambiguity
+    - Ambiguity score >= 30 (above threshold)
+    - Offer options: tcm-api, tcm-web, tcm-bot, tcm-jobs
+    """
+
+    user_request = "valida el servicio de tcm"
+
+    # Phase 0: Should detect ambiguity
+    clarification = request_clarification(user_request)
+
+    # Assertions
+    assert clarification["needs_clarification"] == True, \
+        "Should need clarification for ambiguous service reference"
+
+    assert clarification["ambiguity_score"] >= 30, \
+        f"Ambiguity score {clarification['ambiguity_score']} should be >= 30"
+
+    # Should detect service ambiguity pattern
+    service_ambiguity = next(
+        (a for a in clarification.get("ambiguity_points", [])
+         if "service" in a["pattern"]),
+        None
+    )
+
+    assert service_ambiguity is not None, \
+        "Should detect service ambiguity pattern"
+
+    # Should offer service options containing "tcm"
+    available_options = service_ambiguity.get("available_options", [])
+    tcm_services = [opt for opt in available_options if "tcm" in opt.lower()]
+
+    assert len(tcm_services) > 0, \
+        f"Should offer TCM services, got: {available_options}"
+
+
+def test_regression_check_the_api():
+    """
+    Regression test for: "Check the API"
+
+    Generic reference to "the API" when multiple APIs exist should trigger clarification.
+    """
+
+    clarification = request_clarification("Check the API")
+
+    assert clarification["needs_clarification"] == True
+    assert clarification["ambiguity_score"] > 30
+
+    # Should detect service ambiguity
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "service_ambiguity" in patterns
+
+
+def test_regression_deploy_to_cluster():
+    """
+    Regression test for: "Deploy to cluster"
+
+    Missing namespace specification should trigger clarification.
+    """
+
+    clarification = request_clarification("Deploy to cluster")
+
+    assert clarification["needs_clarification"] == True
+
+    # Should detect namespace ambiguity
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "namespace_ambiguity" in patterns
+
+
+def test_regression_deploy_to_production():
+    """
+    Regression test for: "Deploy to production"
+
+    When project-context says "non-prod" but user mentions "production",
+    should trigger environment warning.
+    """
+
+    clarification = request_clarification("Deploy to production")
+
+    assert clarification["needs_clarification"] == True
+
+    # Should detect environment mismatch
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "environment_ambiguity" in patterns
+
+    # Should have high weight (90)
+    env_ambiguity = next(
+        (a for a in clarification.get("ambiguity_points", [])
+         if "environment" in a["pattern"]),
+        None
+    )
+    assert env_ambiguity["weight"] >= 80, \
+        "Environment mismatch should have high weight"
+
+
+def test_no_clarification_for_specific_prompt():
+    """
+    Test that specific prompts do NOT trigger clarification.
+
+    "Check tcm-api service in tcm-non-prod namespace" is fully qualified
+    and should not need clarification.
+    """
+
+    clarification = request_clarification(
+        "Check tcm-api service in tcm-non-prod namespace"
+    )
+
+    assert clarification["needs_clarification"] == False, \
+        "Specific prompt should not need clarification"
+
+    assert clarification.get("ambiguity_score", 0) <= 30, \
+        "Specific prompt should have low ambiguity score"
+
+
+def test_spanish_keywords_detection():
+    """
+    Test that Spanish keywords are properly detected.
+
+    "Chequea el servicio" should trigger same clarification as "Check the service"
+    """
+
+    clarification = request_clarification("Chequea el servicio")
+
+    assert clarification["needs_clarification"] == True
+
+    # Should detect service ambiguity
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "service_ambiguity" in patterns
+
+
+def test_execute_workflow_without_ask_function():
+    """
+    Test execute_workflow in manual mode (no ask_user_question_func).
+
+    Should return questions for manual handling.
+    """
+
+    result = execute_workflow("Check the API")
+
+    assert result.get("needs_manual_questioning") == True
+    assert "questions" in result
+    assert len(result["questions"]) > 0
+    assert "summary" in result
+
+    # Original prompt not enriched yet
+    assert result["enriched_prompt"] == "Check the API"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

package/tests/tools/test_clarify_engine.py

@@ -1,5 +1,5 @@
 """
-Unit tests for clarify_engine.py
+Unit tests for clarification module
 """
 
 import pytest
@@ -11,7 +11,7 @@ import os
 tools_path = os.path.join(os.path.dirname(__file__), '..', '..', 'tools')
 sys.path.insert(0, tools_path)
 
-from clarify_engine import ClarificationEngine, request_clarification, process_clarification
+from clarification import ClarificationEngine, request_clarification, process_clarification
 
 
 @pytest.fixture
@@ -338,8 +338,7 @@ def test_get_option_metadata_service(engine_with_mock_context):
             "tcm-api": {
                 "tech_stack": "NestJS",
                 "namespace": "tcm-non-prod",
-                "port": 3001,
-                "status": "running"
+                "port": 3001
             }
         }
     }
@@ -349,7 +348,7 @@ def test_get_option_metadata_service(engine_with_mock_context):
     assert "NestJS" in metadata
     assert "tcm-non-prod" in metadata
     assert "3001" in metadata
-    assert "✅" in metadata  # Running status emoji
+    # Status is NOT in project-context (verified in real-time only)
 
 
 def test_get_option_metadata_namespace(engine_with_mock_context):

package/tools/clarification/__init__.py

@@ -0,0 +1,52 @@
+"""
+Clarification Module
+
+Intelligent ambiguity detection and prompt enrichment for Phase 0 of the
+orchestration workflow.
+
+This module detects ambiguous user prompts (e.g., "check the API" when multiple
+APIs exist) and generates targeted clarification questions with rich options
+from project-context.json.
+
+Public API:
+    - execute_workflow(): High-level function for orchestrators
+    - request_clarification(): Detect ambiguity and generate questions
+    - process_clarification(): Enrich prompt with user responses
+    - ClarificationEngine: Core engine class
+    - detect_all_ambiguities(): Pattern-based detection
+
+Example usage:
+    from clarification import execute_workflow
+
+    result = execute_workflow("check the API")
+    enriched_prompt = result["enriched_prompt"]
+"""
+
+from .engine import (
+    ClarificationEngine,
+    request_clarification,
+    process_clarification
+)
+
+from .patterns import detect_all_ambiguities
+
+from .workflow import (
+    execute_workflow,
+    should_skip_clarification,
+    get_clarification_summary
+)
+
+__all__ = [
+    # Main workflow function (recommended for orchestrators)
+    'execute_workflow',
+    'should_skip_clarification',
+    'get_clarification_summary',
+
+    # Lower-level functions (for advanced usage)
+    'ClarificationEngine',
+    'request_clarification',
+    'process_clarification',
+    'detect_all_ambiguities',
+]
+
+__version__ = '1.0.0'

package/tools/{clarify_engine.py → clarification/engine.py}

@@ -52,7 +52,7 @@ class ClarificationEngine:
             }
         """
         # Import patterns here to avoid circular dependency
-        from clarify_patterns import detect_all_ambiguities
+        from .patterns import detect_all_ambiguities
 
         # Step 1: Detect all ambiguities using patterns
         ambiguities = detect_all_ambiguities(user_prompt, self.project_context)
@@ -330,10 +330,10 @@ class ClarificationEngine:
             tech_stack = svc.get("tech_stack", "N/A")
             namespace = svc.get("namespace", "N/A")
             port = svc.get("port", "N/A")
-            status = svc.get("status", "unknown")
-            status_emoji = "✅" if status == "running" else "⏸️"
 
-            return f"{tech_stack} | Namespace: {namespace} | Puerto: {port} | Estado: {status_emoji} {status}"
+            # Status is NOT stored in project-context (must be verified in real-time)
+            # Only show static metadata
+            return f"{tech_stack} | Namespace: {namespace} | Puerto: {port}"
 
         # Namespace metadata
         elif pattern == "namespace_ambiguity" and "namespace_metadata" in ambiguity:

package/tools/clarification/workflow.py

@@ -0,0 +1,205 @@
+"""
+Clarification Workflow Functions
+
+High-level helper functions for orchestrators to integrate Phase 0 clarification
+with minimal code changes.
+"""
+
+import sys
+from typing import Dict, Any, Optional
+
+from .engine import request_clarification, process_clarification
+
+
+def execute_workflow(
+    user_prompt: str,
+    command_context: Optional[Dict[str, Any]] = None,
+    ask_user_question_func: Optional[callable] = None
+) -> Dict[str, Any]:
+    """
+    Execute complete Phase 0 clarification workflow.
+
+    This is the main entry point for orchestrators. It handles:
+    1. Ambiguity detection
+    2. Question generation
+    3. User interaction (if ask function provided)
+    4. Prompt enrichment
+
+    Args:
+        user_prompt: Original user request
+        command_context: Optional context (e.g., {"command": "speckit.specify"})
+        ask_user_question_func: Function to ask questions (e.g., AskUserQuestion tool)
+                                If None, returns questions for manual handling
+
+    Returns:
+        {
+            "enriched_prompt": str,              # Enriched or original prompt
+            "clarification_occurred": bool,       # True if clarification happened
+            "clarification_data": Dict or None,   # Full clarification data (for logging)
+            "questions": List[Dict],              # Questions asked (if any)
+
+            # Only if ask_user_question_func is None:
+            "needs_manual_questioning": bool,     # True if manual question handling needed
+            "summary": str                        # Clarification summary to show user
+        }
+
+    Example (automatic mode - with AskUserQuestion):
+        from clarification import execute_workflow
+
+        result = execute_workflow(
+            user_prompt="check the API",
+            ask_user_question_func=AskUserQuestion  # Claude Code tool
+        )
+        enriched_prompt = result["enriched_prompt"]
+
+    Example (manual mode - for custom UX):
+        result = execute_workflow("check the API")
+
+        if result.get("needs_manual_questioning"):
+            print(result["summary"])
+            for q in result["questions"]:
+                # Show question to user with custom UI
+                # Get user response
+                # Then call process_clarification manually
+    """
+
+    # Step 1: Detect ambiguity
+    clarification = request_clarification(
+        user_prompt=user_prompt,
+        command_context=command_context or {"command": "general_prompt"}
+    )
+
+    # Step 2: Decision point - no clarification needed
+    if not clarification["needs_clarification"]:
+        return {
+            "enriched_prompt": user_prompt,
+            "clarification_occurred": False,
+            "clarification_data": None,
+            "questions": []
+        }
+
+    # Step 3: If no ask function provided, return questions for manual handling
+    if ask_user_question_func is None:
+        return {
+            "enriched_prompt": user_prompt,  # Not enriched yet
+            "clarification_occurred": False,
+            "clarification_data": clarification,
+            "questions": clarification["question_config"]["questions"],
+            "summary": clarification["summary"],
+            "needs_manual_questioning": True
+        }
+
+    # Step 4: Ask user questions (using provided function)
+    try:
+        user_responses = ask_user_question_func(**clarification["question_config"])
+    except Exception as e:
+        # If questioning fails, return original prompt
+        print(f"Warning: Failed to ask clarification questions: {e}", file=sys.stderr)
+        return {
+            "enriched_prompt": user_prompt,
+            "clarification_occurred": False,
+            "clarification_data": None,
+            "questions": [],
+            "error": str(e)
+        }
+
+    # Step 5: Enrich prompt with responses
+    result = process_clarification(
+        engine_instance=clarification["engine_instance"],
+        original_prompt=user_prompt,
+        user_responses=user_responses.get("answers", {}),
+        clarification_context=clarification["clarification_context"]
+    )
+
+    return {
+        "enriched_prompt": result["enriched_prompt"],
+        "clarification_occurred": True,
+        "clarification_data": {
+            "original_prompt": user_prompt,
+            "ambiguity_score": clarification.get("ambiguity_score", 0),
+            "patterns_detected": [a["pattern"] for a in clarification.get("ambiguity_points", [])],
+            "user_responses": user_responses.get("answers", {})
+        },
+        "questions": clarification["question_config"]["questions"]
+    }
+
+
+def should_skip_clarification(
+    user_prompt: str,
+    command_context: Optional[Dict[str, Any]] = None
+) -> bool:
+    """
+    Quick check if Phase 0 should be skipped for this prompt.
+
+    Skip clarification for:
+    - System commands (starts with "/")
+    - Read-only queries with low ambiguity ("show", "get", "list")
+    - Already-specific prompts (includes service name, namespace, etc.)
+
+    Args:
+        user_prompt: User's request
+        command_context: Optional command context
+
+    Returns:
+        True if Phase 0 should be skipped, False otherwise
+
+    Example:
+        if should_skip_clarification("/help"):
+            # Skip Phase 0
+        else:
+            # Execute Phase 0
+    """
+
+    # Skip system commands
+    if user_prompt.strip().startswith("/"):
+        return True
+
+    # For read-only queries, use higher ambiguity threshold
+    read_only_keywords = ["show", "get", "list", "ver", "mostrar", "listar", "view"]
+    if any(keyword in user_prompt.lower() for keyword in read_only_keywords):
+        clarification = request_clarification(user_prompt, command_context)
+        # Higher threshold (50 instead of 30) for read-only operations
+        return clarification.get("ambiguity_score", 0) < 50
+
+    return False
+
+
+def get_clarification_summary(clarification_data: Dict[str, Any]) -> str:
+    """
+    Generate human-readable summary of clarification that occurred.
+
+    Useful for logging or displaying to user.
+
+    Args:
+        clarification_data: Clarification data from execute_workflow()
+
+    Returns:
+        String summary (multi-line)
+
+    Example:
+        result = execute_workflow("check the API")
+        if result["clarification_occurred"]:
+            print(get_clarification_summary(result["clarification_data"]))
+    """
+
+    if not clarification_data:
+        return "No clarification needed"
+
+    original = clarification_data.get("original_prompt", "N/A")
+    score = clarification_data.get("ambiguity_score", 0)
+    patterns = clarification_data.get("patterns_detected", [])
+    responses = clarification_data.get("user_responses", {})
+
+    lines = []
+    lines.append("=" * 60)
+    lines.append("PHASE 0 CLARIFICATION SUMMARY")
+    lines.append("=" * 60)
+    lines.append(f"Original prompt: {original}")
+    lines.append(f"Ambiguity score: {score}/100")
+    lines.append(f"Patterns detected: {', '.join(patterns)}")
+    lines.append(f"\nUser responses:")
+    for question_id, answer in responses.items():
+        lines.append(f"  {question_id}: {answer}")
+    lines.append("=" * 60)
+
+    return "\n".join(lines)

package/tools/context_provider.py

@@ -1,35 +1,12 @@
 import json
 import argparse
 import sys
-import os
 from pathlib import Path
 from typing import Dict, List, Any, Optional
 
 # This script is expected to be run from the root of the repository.
-# Historically the project context lived at `.claude/project-context.json`, but
-# newer installs keep it under `.claude/project-context/project-context.json`.
-# We auto-detect the most common locations (and honor GAIA_CONTEXT_PATH) so agent
-# routing never breaks if the file isn't symlinked to the legacy path.
-def get_default_context_path() -> Path:
-    """Detects the project-context.json location, honoring GAIA_CONTEXT_PATH."""
-    env_override = os.environ.get("GAIA_CONTEXT_PATH")
-    if env_override:
-        return Path(env_override).expanduser()
-
-    candidates = [
-        Path(".claude/project-context.json"),
-        Path(".claude/project-context/project-context.json"),
-        Path("project-context.json"),
-    ]
-
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate
-
-    # Fall back to the legacy expectation; load_project_context will surface error
-    return candidates[0]
-
-DEFAULT_CONTEXT_PATH = get_default_context_path()
+# Project context is always stored at `.claude/project-context/project-context.json`.
+DEFAULT_CONTEXT_PATH = Path(".claude/project-context/project-context.json")
 
 # Path to provider-specific contract files
 # When running from installed project: .claude/config (symlinked)