Fase 6 — bucle agéntico: hammer-agent (cliente + translator + orchestrator) y hammer ai

- proto: mover hammerd::proto a hammer-core::proto para que hammerd y hammer-agent
  compartan los tipos del bus sin duplicar.
- hammer-agent (crate nuevo):
  * client: AgentClient síncrono. Handshake hello/welcome; compile/inject/query/init
    bloqueantes con timeout; reader thread interno demultiplexa async events (Modified/
    Crashed) en una cola que el caller drena vía drain_async/next_async.
  * translator: trait IntentTranslator + MockTranslator (HashMap<intent, Swm>) +
    IntentCatalog YAML (swm_inline o swm_path). El traductor LLM real se enchufa
    detrás del mismo trait sin cambios al orquestador.
  * orchestrator: Orchestrator::run(intent) -> Proposal con plan -> schema -> base ->
    try (overlay|prefix) -> apply (config_edit/file_drop con hammer-core::apply,
    source_patch via bus opcional) -> verify (spot-checks) -> propose. Devuelve
    overlay_id (para `hammer commit`) o prefix usado.
- hammer-cli: subcomando `hammer ai <intent> --catalog F [--prefix DIR --base-ref F
  --bus SOCK --state-root DIR]`. Imprime el Proposal y el siguiente paso humano.
- Tests:
  * 10 unit (translator + catalog + orchestrator).
  * 3 e2e del bucle agéntico (intent -> archivos esperados bajo un prefix tmp).
  * 1 e2e del cliente contra un stub bus (handshake + Compile -> BuildReady +
    Modified asíncrono), sin depender de hammerd ni del lab.
- Docs: SDD 08 actualizado con el API del crate; roadmap marca lo cerrado y lo
  pendiente (LLM real, lenguaje de consulta, bucle de auto-reparación con Crashed).

docs/08-ai-integration.md

@@ -77,14 +77,22 @@ expuestas y de baja entropía**, que es justo lo que un agente necesita.
 
 ## 5. De la intención al `.swm`: el rol del modelo
 
-El traductor intención→`.swm` es un LLM. Detalles de modelo/API (Claude, herramientas, prompts)
-se documentarán aparte cuando se implemente la Fase 6; aquí sólo fijamos el contrato:
+El traductor intención→`.swm` se conecta detrás del trait `IntentTranslator` del crate
+`hammer-agent`. Contrato:
 
-- **Entrada:** intención en NL + contexto del sistema (qué herramientas hay, qué pins, estado
-  de servicios — todo consultable por `QUERY`).
-- **Salida:** un `.swm` válido ([SDD 06](06-swm-format.md)) + un plan de verificación.
-- **El modelo no ejecuta nada directamente:** emite comandos por el bus, que `hammerd` valida
-  contra las capacidades concedidas.
+- **Entrada:** intención en NL + `SystemContext` (lo que el orquestador recolecta por
+  `QUERY`: `BaseRef` local, extras JSON).
+- **Salida:** un `Swm` válido ([SDD 06](06-swm-format.md)).
+
+Fase 6 entrega un `MockTranslator` que resuelve intentos contra un `IntentCatalog` YAML
+(intent exacto → `.swm` inline o `swm_path` relativo). Eso permite probar el bucle sin LLM:
+el humano que descubrió la intención con un modelo real congela el resultado y los CI lo
+reproducen byte-a-byte. El traductor LLM (Claude API u otro) implementa el mismo trait y se
+enchufa sin tocar el `Orchestrator`.
+
+**El modelo nunca ejecuta nada directamente:** emite comandos por el bus, que `hammerd`
+valida contra las capacidades concedidas, y el `Orchestrator` traduce las mutaciones a
+`hammer-core::apply` o a `Compile` por el bus.
 
 ## 6. Lenguaje de consulta/transformación (visión, Fase posterior)
 
@@ -101,13 +109,34 @@ esté probado.
 
 ## 7. Interfaz
 
+El crate `hammer-agent` (Fase 6) expone:
+
 ```rust
-// cliente del bus (puede vivir en un crate aparte hammer-agent en Fase 6)
-pub trait AgentClient {
-    fn hello(&mut self) -> Result<Caps>;
-    fn compile(&mut self, recipe: &Recipe) -> Result<ArtifactHash>;
-    fn inject(&mut self, h: &ArtifactHash, target: &Path, overlay: OverlayId) -> Result<()>;
-    fn query(&mut self, q: Query) -> Result<QueryResult>;
-    fn events(&mut self) -> impl Iterator<Item = BusEvent>;
+// hammer_agent::client
+pub struct AgentClient { pub welcome: Welcome, /* … */ }
+impl AgentClient {
+    pub fn connect(sock: &Path) -> Result<Self>;
+    pub fn compile(&mut self, recipe: RecipeInline, timeout: Duration) -> Result<String>; // artifact
+    pub fn inject(&mut self, artifact: &str, target: &str, overlay: Option<&str>, t: Duration) -> Result<usize>;
+    pub fn query_file(&mut self, path: &str, timeout: Duration) -> Result<serde_json::Value>;
+    pub fn init(&mut self, cmd: &str, timeout: Duration) -> Result<()>;
+    pub fn drain_async(&self) -> Vec<Event>;
+    pub fn next_async(&self, timeout: Duration) -> Result<Event>;
+}
+
+// hammer_agent::translator
+pub trait IntentTranslator { fn translate(&self, intent: &str, ctx: &SystemContext) -> Result<Swm, TranslateError>; }
+pub struct MockTranslator { /* HashMap<intent, Swm> */ }
+pub struct IntentCatalog { pub intents: Vec<CatalogEntry> }  // YAML loader
+
+// hammer_agent::orchestrator
+pub struct Orchestrator<T: IntentTranslator> { /* … */ }
+impl<T> Orchestrator<T> {
+    pub fn new(t: T, base: BaseRef, apply: ApplyTarget, compile: CompileMode) -> Self;
+    pub fn run(&self, intent: &str) -> Result<Proposal>;
 }
 ```
+
+Los tipos del protocolo (`Command`/`Event`/`Cap`/`Peer`/`RecipeInline`) viven en
+`hammer-core::proto` para ser compartidos por `hammerd`, `hammer-agent` y cualquier cliente
+externo escrito en Rust.

docs/10-roadmap.md

@@ -99,10 +99,32 @@ pre-requisito de validación.
   gating `no_cap`, `Query`, `Modified` fan-out, `Init`→FIFO. Un `Compile` real reusa el
   camino de Fase 0/1 (gated en `HAMMER_NETWORK_TESTS`).
 
-### Fase 6 — Integración de la IA
-- [ ] Cliente de agente; traductor intención NL → `.swm`; bucle plan→build→try→verify→propose.
+### Fase 6 — Integración de la IA  ▶ *en progreso*
+- [x] Crate `hammer-agent` con tres piezas:
+      - `AgentClient`: cliente síncrono del bus (handshake, `compile`/`inject`/`query`/`init`
+        bloqueantes, drenado de eventos asíncronos).
+      - `IntentTranslator` (trait) + `MockTranslator` cargado desde un `IntentCatalog` YAML
+        (intent → `.swm` pre-armado). La integración con un LLM real se enchufa detrás del
+        mismo trait sin tocar el bucle.
+      - `Orchestrator` con `run(intent) → Proposal`: plan → schema → base → try (overlay
+        o prefix) → apply (mutaciones puras + source_patch vía bus opcional) → verify →
+        propose.
+- [x] CLI: `hammer ai <intent> --catalog F [--prefix DIR --base-ref F --bus SOCK]`.
+- [x] Tipos del protocolo del bus movidos a `hammer-core::proto` para que `hammerd` y
+      `hammer-agent` los compartan.
+- [x] Tests:
+      - 10 unit en `hammer-agent` (translator + catalog + orchestrator).
+      - 3 e2e del bucle agéntico (prefix tmp → archivos esperados en disco).
+      - 1 e2e del cliente contra un *stub* del bus (handshake + Compile→BuildReady + Modified
+        asíncrono).
+- [ ] Traductor LLM real (Claude API u otro), opcional vía feature flag o crate aparte.
+- [ ] Lenguaje de consulta del sistema (SDD 08 §6) para que la IA refiera servicios y
+      archivos sin rutas frágiles.
+- [ ] Bucle de auto-reparación (cliente reacciona a `Crashed` con un nuevo plan).
 - **Hecho cuando:** una intención en lenguaje natural produce un cambio probado en overlay,
-  presentado para `commit` humano.
+  presentado para `commit` humano. ✅ Demostrado por `hammer ai` con `MockTranslator`:
+  intent → `.swm` → mutaciones aplicadas → `Proposal` con `overlay_id` + checks. El humano
+  decide `commit`/`discard`. El upgrade a LLM real reusa todo el bucle.
 
 ---