Roadmap dotforge

June 3, 2026 · View on GitHub

Estado actual: v4.0.0 (2026-06-03) — Major release. Override capture loop closes practices↔behaviors (bash script + SessionStart hook). Audit checklist items 16-17 (workflow availability + override loop active). domain/workflow-economics.md documents v4 PoC findings rejecting "workflow-native everywhere" thesis on cost-quality grounds. workflows/watch.js ships as REFERENCE implementation (not promoted to /forge watch default). Migration script with --dry-run + atomic backup + --rollback.

Completado

v4.0.0 — Override capture loop + workflow economics rule + audit items 16-17 (2026-06-03)

Phase 0 PoC (4 smoke tests of workflows/watch.js) rejected the "workflow-native everywhere" thesis. v4 scope reduced from "refactor every multi-step skill" to override loop + audit items + workflows-as-reference.

Override capture loop (Phase 1)

scripts/process-override-log.sh (260 líneas bash, 10/10 tests verde, idempotente)
session-start-process-overrides.sh wrappers (template + .claude/) wired in SessionStart
Processes .forge/audit/overrides.log, agrupa por (project, behavior_id, tool_name) en ventana 30d, crea practices/inbox/auto-override-*.md cuando count ≥ 3
Cost: 0 LLM calls, pure bash

Workflow economics (lección del PoC)

domain/workflow-economics.md (nueva rule, ~110 líneas) — decision matrix workflow vs skill, 10 token economy principles, per-stage model routing
4 PoC smoke tests medidos: workflow refactor de /forge watch = 4-25x más caro que baseline. Verify-sin-WebSearch causa quality regression
workflows/watch.js queda como REFERENCE implementation. /forge watch sigue siendo bash skill (production tool)

Audit checklist items 16-17 (Phase 2)

Item 16: workflow availability (workflows/ dir + meta block)
Item 17: override capture loop active (log + hook wired)
skills/audit-project/SKILL.md extendido con transition note: v3.x dotforge auto-passes items 16-17 (informational); v4.0+ scores normally

Migration tooling (Phase 3)

scripts/migrate-v3-to-v4.sh con --dry-run mandatorio, atomic .claude/ backup, --rollback
4 acciones evaluadas independientemente: install hook, wire in settings, init log, update manifest
NO toca CLAUDE.md, behaviors, rules, agents, commands
docs/v4/MIGRATION-V3-TO-V4.md guía completa con waves recomendadas

Recomended rollout (12 proyectos managed)

Wave 1 pilot: vault-bot
Wave 2 heavy/production: dotforge (self) + InviSight-iOS + TRADINGBOT + cotiza-api-cloud + jira-nbch
Wave 3 rest: cds-dashboard + openclaw + derup + crm + Whassap signals
Skip: SOMA + SOMA2 (archived)

v3.13.0 — Workflow security boundary + ultracode runtime + v2.1.158-161 sync (2026-06-03)

/forge update procesa 6 prácticas del watch upstream 2026-06-03. 1 breaking-ish, 4 medium, 1 low-priority bundle.

Security boundary clarification

Workflow subagents siempre corren en acceptEdits regardless of session permission mode (incluye plan). File edits auto-aprobados. permissions.deny es el único backstop kernel-level. Documentado en domain/workflow-automation.md + domain/workflow-and-ultracode-policy.md + domain/permission-model.md.
v2.1.160 acceptEdits prompts — shell rc files always prompt; build-tool config (.npmrc/.yarnrc*/bunfig.toml/.bazelrc/.pre-commit-config.yaml/.devcontainer/) prompts en acceptEdits. Defense-in-depth con sandbox.filesystem.denyWrite.

Ultracode runtime layer

/effort ultracode activator runtime: xhigh + auto-workflow orchestration por substantive task. Session-only.
/deep-research bundled workflow documentado.
session-startup.sh tier brief actionable: production → "Activate now: /effort ultracode".

Behavior changes

v2.1.160 trigger keyword workflow → ultracode (setting key unchanged).
v2.1.161 PostToolBatch failure isolation — failed Bash no longer cancels other parallel calls.

Small additions bundle

Mantle como 4to enterprise provider · CLAUDE_CODE_ENABLE_AUTO_MODE=1 opt-in v2.1.158 · claude mcp ${VAR} no expandido (security fix v2.1.161) · grep single-file satisface read-before-edit · OTEL metric labels + tool_parameters · claude agents muestra done/total.

v3.12.1 — Housekeeping completar /forge update 2026-06-01 (2026-06-02)

Trae a main los archivos del /forge update del 2026-06-01 que habían quedado sin commitear. Sin features nuevos.

v3.12.0 — Workflow + Ultracode policy con defaults por tier (2026-06-02)

Conceptos canónicos

Workflow = TOOL (orquestación multi-agente, v2.1.154+). Por tarea.
Ultracode = MODE (adversarial verify + workflow-first + plan-mode + structured output). Por proyecto, vía tier en registry.

Nuevas piezas

domain/workflow-and-ultracode-policy.md (nueva, 65 líneas) — política canónica con 5 criterios (C1 Blast radius, C2 Domain risk, C3 Ambiguity, C4 Reversibility, C5 Prior failure), 4 tiers, portfolio table para 12 proyectos.
/forge ultracode-check (slash command) — lee tier + git state + last-startup, aplica 5 criterios, output "ON | CONSIDER | OFF".
session-startup.sh — agrega bloque Ultracode tier: <tier> — <hint>.

Diseñado con Workflow tool (4 fases, 9 agentes, adversarial verify) — verify atrapó 4 issues críticos + 2 mejoras de clasificación.

v3.11.0 — /workflows TODO resuelto + 4 más (2026-06-01)

/forge update desde watch 2026-06-01. 5 inbox → active, 1 deferred.

domain/workflow-automation.md — TODO de /workflows resuelto. Coverage completa v2.1.154+: declarative meta, 5 primitivas (agent/parallel/pipeline/phase/log), schema validation, concurrency, budget, resume.
Worktree lifecycle — auto-unlock on agent finish, EnterWorktree mid-session switch. sync-all-repos/SKILL.md extendido con detección.
StopFailure matchers documentados (rate_limit/authentication_failed/billing_error/server_error). template/hooks/session-report.sh extendido.
Agent frontmatter hooks documentados arquitecturalmente en domain/agent-orchestration.md.
Settings hardening bundle — claudeMd inline managed key, ConfigChange matchers, PowerShell if: pattern fix, settings.json parsing resilience.

v3.10.1 — `/forge sync-all` skill (2026-06-01)

Nuevo skill sync-all-repos — descubre cada repo GitHub-backed en la máquina, clasifica (parallel + timeout), auto-ejecuta pull/push/rebase para casos obvios, delega dirty/non-main a Claude. Maneja: macOS Finder duplicates (* 2.*), worktree submodule traps, stale lock files.

Diseñado para workflow Mac↔VPS sin coordinación directa. .dotforge-sync-ignore como opt-out marker.

v3.10.0 — Sync from Claude Code v2.1.144→v2.1.152 (2026-05-27)

v3.9.1 — Upstream security fixes propagated (v2.1.145→v2.1.149) (2026-05-27)

v3.9.0 — Sync from Claude Code v2.1.141-143 (2026-05-22)

/forge watch + /forge update procesando 13 items del inbox (acumulado 2026-05-18 a 2026-05-19). 8 incorporados, 3 rechazados (1 informational sin acción, 2 auto-stubs), 2 diferidos (Windows / enterprise federation).

Domain rules

hook-events.md — nueva sección "Hook JSON output fields (universal)" con terminalSequence (v2.1.141+); Stop hook contract con 8-block convergence cap + CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.
hook-architecture.md — Stop hook convergence contract con patterns (counters en .claude/session/, systemMessage en vez de block).
model-ids.md — fast mode default = Opus 4.7 (v2.1.142+) con CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE opt-out.
cli-flags.md — claude agents documentado como launcher con 9 flags. Env vars nuevas.
parallel-sessions.md — worktree.bgIsolation: "auto"|"none" con trade-offs (Bazel/codegen). claude agents como launcher con persistencia en /bg detach.
compaction-strategy.md — 4ª modalidad: rewind + "Summarize up to here" (v2.1.141).

Skill + docs

plugin-generator — flat (root SKILL.md, v2.1.142+) vs structured shapes; plugin.json con dependencies: [] per v2.1.143 enforcement.
docs/best-practices.md — nueva subsección "Recent additions (v2.1.141-143)" con 6 entries.

v3.8.1 — Docs domain migration (2026-05-18)

Refactor de referencias docs.anthropic.com → code.claude.com en domain rules y link rules. domain/cli-flags.md last-verified bumped.

v3.8.0 — Sync from Claude Code v2.1.129→v2.1.140 + new domain/auth.md (2026-05-13)

Nueva domain/auth.md documentando precedence: ANTHROPIC_API_KEY > apiKeyHelper > CLAUDE_CODE_OAUTH_TOKEN > Claude.ai login > Console login. v2.1.139+ rule: API-key presence disables Remote Control, /schedule, notification preferences (incluso con Claude.ai login).
CI canonical path documentado: claude setup-token para CI runs con Claude subscription.
Anti-patterns registrados: ANTHROPIC_API_KEY en ~/.bashrc silently disables features; sharing OAuth token entre CI y dev machine.
Updates en hook-events.md, hook-architecture.md, parallel-sessions.md, cli-flags.md, agent-orchestration.md cubriendo --bg, claude agents, worktree.baseRef, --from-pr, etc.

v3.7.1 — Evidence-based compaction policy: 80% threshold (2026-05-05)

Política basada en evidencia: academia (Liu, Chroma, Kamradt) + práctica de campo (Boris Cherny, Daniel San, Avthar, Paweł Huryn). Threshold canónico: 80% del context window.

domain/compaction-strategy.md (nueva, 70 líneas) — política con citas, /compact vs /clear vs subagent, anti-patterns, cache economy.
/forge compact-task (slash command) — wrapper de /compact con hint estandarizado.
/forge context-status (slash command read-only) — reporte de uso + cache health.
pre-compact-warning.sh (UserPromptSubmit hook) — alerta proactiva al 80% (warning) y 90% (urgent). Configurable via env vars.
docs/internal/compaction-strategy.md (200 líneas) — guía operacional con flow chart, decision tables, configuración por tipo de proyecto.

v3.7.0 — Smart init: startup snapshot + drift + Setup validation (2026-05-05)

Cierra la simetría con auto-compact (v3.6.3): el SessionStart ahora captura, compara y persiste el estado inicial; el Setup hook valida invariantes antes de cualquier tool call.

.claude/hooks/session-startup.sh — wired en SessionStart (todos los source ≠ compact). Captura branch, HEAD, working tree, edits 24h en .claude/, TODOs, behaviors disabled. Compara HEAD con startup-history/ para detectar drift. Inyecta brief al contexto sólo si hay algo notable.
.claude/hooks/pre-session-check.sh — wired en Setup (init, maintenance). Valida JSON/YAML, hooks executable, block-destructive.sh ejecutable. Exit 2 bloquea session start.
Histórico rotatorio — últimos 5 snapshots bajo startup-history/<ISO>.md.
Propagación a 12 proyectos — scripts/sync_all.py + scripts/wire_hooks_all.py. 22 hooks copiados, 33 wirings agregados, 11 post-compact.sh actualizados al template v3.7.0 (filter logic). 0 customizaciones detectadas, 0 errores.

v3.6.3 — Smart auto-compact: filter + rotating history (2026-05-05)

Capa de filtrado encima del compact_summary. scripts/compact-filter.py colapsa fenced blocks > 40 líneas, runs ≥ 30 líneas no-protegidas, párrafos triplicados. Nunca borra headings, paths, decision/error/fix lines. Hook post-compact.sh pipea por el filter, fallback al raw si falla. Histórico de los últimos 5 checkpoints bajo .claude/session/compact-history/.

Verificación: synthetic verbose 2253B → 730B (68% reducción), real dense 22453B → 22447B (~0%, no daña).

v3.6.2 — Cierre de pendientes de auditoría (2026-05-05)

detect-claude-changes.sh con signal gate (skip si TOTAL < 15 archivos AND nada estructural)
not-applicable → informational en metrics, frontmatters, docs (validation rate honesta: 0/19 = 0%)
registry/projects.yml header reescrito como EXAMPLE / REFERENCE
domain/parallel-sessions.md 81 → 38 + nuevo domain/cli-flags.md (53 líneas)

v3.6.1 — Auditoría crítica + pulidos de calidad (2026-05-05)

behaviors/index.yaml: search-first.enabled: false (counter=7, escaló a soft_block, deshabilitado por user en sesión)
Hooks generados de search-first eliminados → PreToolUse: 8 → 6 hooks
domain/permission-model.md dividido (112 → 59 líneas) + nuevo domain/permission-managed-settings.md (60 líneas)
9 backups huérfanos .bak.20260428-* borrados (dotforge + 8 proyectos)

v3.6.0 — Sync from CC v2.1.120-128 round 2 (2026-05-05)

7 prácticas captadas e incorporadas en una pasada de /forge watch. Setup event documentado. PostToolUse updatedToolOutput generalizado a todos los tools. 5 managed-only enterprise fields. alwaysLoad MCP option. workspace reserved name.

v3.5.0 — Sync from CC v2.1.120-128 + agent memory checklist (2026-05-05)

11 prácticas. disable-model-invocation, ${CLAUDE_EFFORT}, plugin-distribution.md (PLUGIN_DATA + multi-seed). Agent memory checklist en architect/code-reviewer/implementer/security-auditor.

v3.4.1 — Backtesting ADR gate rule (2026-04-27)

stacks/trading/rules/backtesting-adr-gate.md — PSR/DSR gate para baseline ADRs (Bailey & López de Prado 2012, 2014).

v3.4.0 — Sync upstream + audit/behavior fixes (2026-04-26)

/forge watch pass contra code.claude.com cubriendo Claude Code v2.1.92 → v2.1.119. 14 prácticas aceptadas (12 upstream + 2 operativas), 6 rechazos auto-generados, 1 deferred.

Domain rules

hook-architecture.md / hook-events.md: catálogo de eventos a 33+ con UserPromptExpansion (blockable, slash command expansion) y PostToolBatch (blockable, fin de batch paralelo). Quinto tipo de hook mcp_tool con ${tool_input.*} substitution. PostToolUse/PostToolUseFailure ahora reciben duration_ms. UserPromptSubmit puede setear hookSpecificOutput.sessionTitle.
auto-mode.md: placeholder "$defaults" para autoMode.allow|soft_deny|environment (extiende vs reemplaza built-in classifier). Nota sobre native macOS/Linux builds que pliegan Glob/Grep en Bash.
permission-model.md: tightening v2.1.113 (Bash(find:*) ya no auto-aprueba -exec/-delete; deny matching sobre wrappers env/sudo/watch/ionice/setsid; macOS /private/{etc,var,tmp,home} como targets peligrosos en Bash(rm:*)). PowerShell auto-approval (v2.1.119). Glob(...)/Grep(...) specifiers son platform-dependent.
context-control-patterns.md: TUI modes (tui setting, /tui, autoScrollEnabled); idle-return recap (/recap, awaySummaryEnabled, CLAUDE_CODE_ENABLE_AWAY_SUMMARY). Coexistencia documentada con last-compact.md.
parallel-sessions.md: superficie completa de CLI flags (--name, --tools, --strict-mcp-config, --system-prompt[-file], --input-format, --include-partial-messages, --debug-file, --disable-slash-commands, --remote-control, --allow-dangerously-skip-permissions, --plugin-dir, --ide, --betas, --channels) + subcomandos (claude install, auth, agents, auto-mode, remote-control, setup-token).
_common.md: Git section actualiza con attribution.commit/pr (deprecates includeCoAuthoredBy) y prUrlTemplate para self-hosted.

Operativos

behaviors/verify-before-done/behavior.yaml: regex extiende a bash tests/*.sh, bash <path>/test-*.sh, ./tests/*.sh. Resuelve git push desde dotforge soft-blocked tras bash tests/test-*.sh legítimo.
audit/checklist.md item 14: scoring requiere ENFORCEMENT (hook compilado en .claude/hooks/generated/ AND referencia en settings.json), no solo declaración en behaviors/index.yaml. Cierra el falso positivo que premiaba a proyectos con 1/1 sin efecto runtime.
docs/claude-vs-forge.md: /usage como comando canónico; /cost y /stats son atajos desde v2.1.118.

Inbox lifecycle

14 → active/ (12 upstream + audit-item-14 + verify-before-done-regex). 6 capturas auto-generadas *-session-changes rechazadas. 1 diferida (agent-memory-underused, tag needs-more-info). metrics.yml con 14 entries nuevas + 8 monitoring bumps.

v3.3.1 — Fix session-report.sh malformed JSON (2026-04-21)

Bug silencioso de 5 meses: el hook session-report.sh corrompía cada archivo JSON bajo ~/.claude/metrics/<slug>/*.json en los 12 proyectos registrados (54 archivos corruptos desde 2026-03-22). /forge insights degradaba silenciosamente a análisis retroactivo de git-log.

Causa raíz (dos bugs encadenados): (1) grep -c ... || echo "0" emite "0\n0" cuando no hay match (GNU grep -c retorna "0" exit code 1 → || dispara → JSON queda con valores multi-línea); (2) cascada — un archivo corrupto previo hacía fallar la aritmética en el siguiente write, dejando "sessions": ,.

Fix: separación grep -c + sanitización ${var//[!0-9]/} + default ${var:-0}. Helper _jq_num() que valida output numérico antes de aritmética. Pre-validación con jq -e . y restart limpio si el archivo previo está corrupto. Propagador scripts/fix-session-metrics.sh aplicado a 9 proyectos.

v3.3.0 — MEDIUM sync + integrations/channels (2026-04-21)

Watch pass del 2026-04-21. Seis prácticas incorporadas (dos security-relevant en monitoring, cuatro doc-drift). /forge audit script-version (scripts/audit_all.py) para batch.

v3.2.0 — Domain sync v2.1.108 → v2.1.114 + block-destructive hardening (2026-04-19)

Watch pass cubriendo Claude Code v2.1.108 → v2.1.114. Hardening de block-destructive.sh contra compound bash y env-var prefix bypass. Six prácticas incorporadas.

v3.1.2 — SSH/VPS persistence loop (2026-04-17)

domain/infra.md como rule canónica para persistir SSH host config + deploy commands + service names entre sesiones. Cierra el problema de "Claude no recuerda cómo deployar" tras /clear.

v3.1.1 — Doc fix `showThinkingSummaries` (2026-04-15)

Hotfix de domain rule: showThinkingSummaries se documentaba como si su toggle tuviera impacto operativo. Por spec oficial es puramente cosmético — no reduce gasto de thinking. Agregado alwaysThinkingEnabled como knob real de costo. Sin impacto en runtime.

v3.1.0 — Domain knowledge sync (2026-04-15)

Watch-upstream pass contra code.claude.com/docs cubriendo Claude Code v2.1.70 → v2.1.109. Ocho practices aceptadas, tres rechazadas (auto-stubs).

Domain rules actualizadas

hook-architecture.md: events count corregido 27 → 31 sobre tres ciclos (session-level, turn-level, tool-loop, async/side). InstructionsLoaded, Elicitation/ElicitationResult, PreCompact blockable desde v2.1.105.
permission-model.md: nuevas secciones Enterprise managed settings (managed-settings.d/, allowManagedHooksOnly, allowedChannelPlugins, forceRemoteSettingsRefresh) y Dynamic permissions from hooks (addRules/replaceRules/removeRules/setMode/addDirectories/removeDirectories).
hook-events.md: PreCompact blockability + payload de InstructionsLoaded + sección de elicitation events.
model-ids.md: default effort cambió medium → high en v2.1.94.

Template

settings.json.tmpl: nueva ask: list de 18 entries cubriendo rm/chmod/npm-pip install/docker run/kubectl apply-delete/gcloud/aws/terraform apply-destroy/git push-rebase-cherry-pick. Cierra el gap entre allow: total y deny: total.
block-destructive.sh: verificado vs compound bash bypass class fixed en v2.1.98 — el hook usa grep -qiE sobre el comando completo, no es vulnerable. Test ls && rm -rf / → blocked. Limitaciones documentadas (eval, payloads codificados) con cross-ref a sandbox.enabled.

Behaviors rollout

4 proyectos piloto con v3 behaviors compilados y wired: dotforge (worktree), cotiza-api-cloud, TRADINGBOT, jira-nbch.
Hallazgo: jira-nbch tenía hooks wired desde el setup inicial pero le faltaba scripts/runtime/lib.sh — fallaba silenciosamente. Restored.

v3.0.0-alpha.1 — Behavior Governance Phase 1 (2026-04-13)

Primer aterrizaje del layer v3: runtime + compilador + search-first end-to-end + detección de override + CLI /forge behavior. Cinco piezas del SCOPE de Fase 1 cumplidas. No reemplaza v2.9: coexiste como capa adicional opt-in.

Spec closure (2 commits de docs)

docs/v3/SCOPE.md alineado con docs/v3/RUNTIME.md — mkdir-based locking como decisión única (eliminación de flock)
docs/v3/RUNTIME.md §4 + SCHEMA.md §3.5 + SPEC.md §2.3: modelo de flags formalizado (session-scoped, shape cerrado, set_flag/check_flag con on_present/on_absent obligatorios)

Runtime (`scripts/runtime/`, 454+154 líneas lib.sh + 8 tests)

.forge/runtime/state.json con schema versionado, mkdir-based lock 2s + PID stale detection, atomic tmp+mv write, corruption recovery
TTL 24h inline purge en cada mutación (jq pipeline)
Counter increment, flag set/check/consume atómicos, _forge_run_mutation choke point
Pure functions: forge_resolve_level, forge_level_max
Tests: concurrencia paralela (10 increments), flag lifecycle, TTL, corruption, stale lock, pending_block
.gitignore extensions: .forge/runtime/, .claude/worktrees/

Compilador (`scripts/compiler/`, ~320 líneas + 1 test)

YAML → bash hook por trigger via python3 + pyyaml (no yq dependency)
Hook template self-contained: fuentea lib.sh via FORGE_LIB_PATH env var o relative anchor fallback
Set_flag hooks minimales (30 líneas), check_flag/evaluate hooks con helpers completos solo cuando on_absent: violate los necesita
Settings.json snippet con {type, command} object format (requerido por Claude Code, NO strings planos)
Template variables sustituidas via sed: {behavior_name}, {counter}, {tool_name}, {level}, {threshold}

search-first end-to-end (`behaviors/search-first/`, 5 scenarios)

behavior.yaml canónico: Grep|Glob|Read → set_flag, Write|Edit → check_flag con consume/violate
behaviors/index.yaml catalogue file
Scenarios: happy path (Grep→Write consume), idempotent set, alternating, escalation silent→nudge→warning→soft_block, override reinvocation

Override detection via reinvocation (RUNTIME.md §12 + 1 test unit + 1 scenario e2e)

pending_block shape: {tool_input_hash, blocked_at} en behavior state
forge_tool_input_hash — sha256 truncado a 40 hex chars de canonical JSON
forge_pending_block_try_override — match + window check + audit trail triple-write
Ventana default 60s via FORGE_OVERRIDE_WINDOW_SECONDS env var
Corrige SPEC.md §6.2 que originalmente asumía PermissionDenied event hook (solo dispara para auto-mode, no para PreToolUse blocks — verificado empíricamente)

`/forge behavior` CLI (`scripts/forge-behavior/`, ~290 líneas + 4 tests)

status [--session SID] — tabla project + runtime con counters, levels, overrides, pending
on|off <id> [--project | --session SID] — project muta index.yaml via pyyaml, session escribe a state.json
strict|relaxed <id> — project-scope, muta escalation thresholds (halve / double)
Hook preamble short-circuita cuando behavior_overrides[bid].enabled == false
skills/forge-behavior/SKILL.md como wrapper para Claude Code

Prueba viva end-to-end en sesión Claude Code real (`~/tmp-v3-live`)

7 prompts secuenciales → escalation silent→nudge→nudge→warning→warning→soft_block observable en pantalla real
permissionDecision: "deny" del hook interpretado por Claude Code como permission denial (respeto SPEC §5.5 al pie de la letra)
Emergent behavior: Claude Code leyó state.json post-block por iniciativa propia y explicó el pending_block mechanism al usuario sin que se le pidiera
Hallazgo empírico #1: /clear resetea session_id en hook payloads → behaviors session-scoped evadibles vía /clear con zero audit trail. Documentado en RUNTIME.md §3 y capturado en practices/inbox/2026-04-13-v3-clear-creates-session-boundary.md con 3 fixes propuestos para Fase 2.
Hallazgo empírico #2: flag masking override — si hay un flag presente cuando viene retry post-soft_block, el path forge_flag_consume short-circuita antes del try_override, el retry pasa pero sin audit trail. No verificable en vivo por el /clear, verificable por code inspection, regression test en Fase 2.

Métricas Fase 1

9 commits en branch v3-fase1 (1 spec alignment + 1 spec extension + 5 feature + 1 live findings + 2 doc updates)
18 tests verdes (8 runtime + 1 compiler + 5 e2e + 4 CLI)
~3000 líneas netas entre código, tests y spec updates
0 regresiones sobre v2.9.1 existente
Zero breaking changes — v3 es aditivo, v2.9 sigue funcionando sin tocar

v2.9.0 — Hardening + Portability + Upstream Alignment (2026-04-05)

Consolidación de confiabilidad basada en Codex review + alineación con Claude Code v2.1.84–v2.1.92.

Fix: score.sh --json (heredoc Python roto), check-updates.sh (path), detect-stack-drift.sh (schema + mensaje), hookify (paths), injection scan (falso positivo)
Portabilidad: timeout/md5sum/shebangs portables a macOS + Linux + WSL + Git Bash
Nuevo: install.sh one-liner con detección de plataforma
Upstream: 27 hook events, 6 permission modes, 1M context GA, paths: YAML list, Claude 3 Haiku deprecated
Nuevas domain rules: auto-mode.md, hook-events.md
Manifest: campo stacks agregado al schema
README: tagline "governance", lifecycle hero, Works with, Requirements con WSL
Auditoría completa: 12 proyectos, 8 perfect, avg 9.8/10
Migración claude-kit → dotforge completada en todos los proyectos
Deny list global alineada (+5 entries, **/recursive globs)
.gitignore: pycache/, *.pyc

v2.8.0 — Internals Analysis + P0 Fixes + P1 Alignment (2026-04-05)

Reverse engineering de 5 repositorios + alineación de dotforge con internals verificados de Claude Code.

P0 — Bugs y Seguridad

Fix: session-report.sh JSON corruption, block-destructive.sh regex, deny patterns faltantes
Fix: agent frontmatter (allowed-tools: vs tools:, campo memory: inválido) en 7 agentes
Fix: redis glob **/*stream* → **/*redis*, _common.md excedido, Bash(cat *) removido
Nuevo: Bash(make *) en template base

P1 — Internals Alignment

Fix: node-express glob narrowed a backend paths — elimina overlap con react-vite-ts
Fix: data-analysis glob removido .py — elimina overlap con python-fastapi
Fix: auto-mode safe permissions — reemplazados python3/node/npm/aws/gcloud con tool commands específicos en 6 stacks
Nuevo: ToolSearch Step 0 en watch-upstream + scout-repos (deferred tools discovery)
Nuevo: CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 en template settings
Nuevo: async hooks documentados en hookify (async flag, asyncRewake, streaming)
Mejora: detect.md — hookify + trading stacks, pyproject.toml refinado, priority rules
Cambio: test-runner model haiku → sonnet (escribe tests, requiere razonamiento)
Nuevo: 5K token output budget en 6 agents + SendMessage continuation
Nuevo: system prompt override patterns en python-fastapi, java-spring, go-api
Nuevo: context: fork en 5 skills pesadas

Domain Rules — Source-Verified

6 domain rules actualizadas: hook-architecture (25 eventos), permission-model (5-step cascade), context-window-optimization (5-tier compaction), rule-effectiveness (frontmatter completo), agent-orchestration (task types, AGENT_TEAMS env var), prompting-patterns (system prompt conflicts)

Documentation

docs/internal/claude-code-internals-analysis.md — cross-repo reverse engineering (5 repos)
docs/internal/improvement-plan-internals.md — 36 items priorizados P0-P3
docs/internal/feature-flags-reference.md — env vars, settings keys, flags internos, GrowthBook gates
Análisis de reimplementaciones Python (nanocode 250 líneas, nano-claude-code 6.2K líneas)

v2.7.1 — Hook Architecture Corrections + Expansion (2026-03-30)

Corrección: PreCompact es non-blocking (exit code ignorado)
Verificado: PostCompact recibe compact_summary + trigger
4 eventos de hook documentados: PermissionRequest, SubagentStart, CwdChanged, StopFailure
Hook types http, prompt, agent documentados en hookify
Corrección rule-effectiveness.md: eager loading (globs:) vs lazy loading (paths:)

v2.7.0 — Domain Knowledge Layer + Context Continuity (2026-03-30)

template/rules/domain-learning.md: regla globs:**/* para persistir descubrimientos de dominio
/forge domain extract|sync-vault|list: skill de gestión de conocimiento de dominio
template/hooks/post-compact.sh + session-restore.sh: context continuity post-compaction
/forge init pregunta dominio/rol; /forge sync skipea .claude/rules/domain/

v2.6.1 — Practices Pipeline + Python Debugging (2026-03-24)

2 prácticas promovidas desde cotiza-api-cloud (root cause first, package naming)
7 prácticas deprecadas

v2.6.0 — Audit CI + Stack Drift + MCP (2026-03-21)

audit/score.sh: script standalone para PRs, 12 checks, score 0-10
detect-stack-drift.sh: PostToolUse hook para dependencias nuevas
/forge mcp add <server>: instala MCP server template en 1 comando
MCP version pinning + mcp/update-versions.sh
Model IDs explícitos en model-routing.md

v2.5.0 — Capture + MCP + Model Routing (2026-03-21)

/forge capture auto-detección + /cap alias
MCP server templates: github, postgres, supabase, redis, slack
template/rules/model-routing.md: criterios haiku/sonnet/opus
7 agents con modelo explícito

v2.4.0 — Init + Global Sync + Integrations (2026-03-21)

/forge init: quick-start con 3 preguntas, detección de idioma
/forge global sync: auto-pull + resync ~/.claude/
OpenClaw integration, plugin marketplace, hook profiles, session report

v3.0.0 — Behavior Governance (en progreso)

Fase 2 — Catálogo + fixes de hallazgos empíricos (2-3 semanas post-alpha.1)

Catálogo core de behaviors: verify-before-done, no-destructive-git, respect-todo-state, plan-before-code, objection-format. Cada uno con behavior.yaml + scenarios tests.
Reorder check_flag template — forge_pending_block_try_override debe correr antes de forge_flag_consume para cerrar el flag-masking-override gap detectado en la prueba viva.
scope: project para behaviors session-clear-resistant (no-destructive-git es el candidato #1). Persiste counters en project state, no en session state, inmune a /clear.
Sweep de pending_blocks huérfanos en hook init — si detecta una sesión distinta con pending_block no expirado, append a audit log como session_abandoned_with_pending_block.
/forge audit dimensión "behaviors coverage" — item scored que cuenta qué fracción de eventos relevantes tienen behaviors registrados.
Tests por behavior — cada behavior en behaviors/<id>/tests/ con al menos 1 happy path + 1 violation + 1 escalation scenario.
Wiring del comando — /forge behavior como sub-comando nativo en global/commands/forge.md (hoy se invoca directo al CLI).

Fase 3 — Release (1-2 semanas)

README rewrite — diferencial de v3 visible en las primeras 40 líneas. Hoy README habla solo de config governance, no de behavior governance.
CHANGELOG v3.0.0 formal
Migration guide v2.9 → v3 (opt-in, no rompe 2.9)
Benchmark real corrido en SOMA o InviSight — medir impacto del behavior layer en comportamiento observable de Claude
GIF demo de search-first escalando en un proyecto real
Tag v3.0.0 release
Marketplace submission update con features v3

Pendiente legacy (movido de v2.8.0, sin urgencia)

PermissionRequest hook: auto-allow para operaciones known-safe
SubagentStart hook: inyectar contexto de dominio a subagentes
CwdChanged hook: recargar reglas de dominio al cambiar directorio
StopFailure hook: capturar errores de API, sugerir retry strategy
/forge doctor: diagnóstico de entorno con semáforo
trading stack: reglas domain-specific — test en proyecto real

Stack `llm-python` (diferido)

Para proyectos Python con LLM APIs (anthropic, openai, langchain, litellm)
Rules: API keys, retry con backoff, no loggear content, costeo antes de batch ops

Practice effectiveness validation

Completar recurrence checks de prácticas en monitoring
Promover prácticas validadas a reglas permanentes

MCP templates nuevos

mcp/filesystem/: config con paths permitidos, deny ~/.ssh, ~/.aws
mcp/brave-search/: config read-only con BRAVE_API_KEY

Audit v2

Domain knowledge como item scored (actualmente informacional)
Hook coverage score: % de eventos utilizados vs disponibles

Próximo (planificado, sin versión asignada)

Nuevo stack: prompt-engineering

Para proyectos que configuran Claude Code (meta-configuración)

Nuevo skill: `/forge context-budget`

Estima costo en tokens de la configuración actual

Hooks para eventos no usados

PostToolUseFailure → error tracking automático (parcial: domain rules ya documentan duration_ms field desde v3.4.0)
FileChanged → auto-reload patterns
TaskCreated/TaskCompleted → métricas de orquestación
PermissionDenied → audit trail
PostToolBatch → end-of-batch validation (nuevo desde v3.4.0)
UserPromptExpansion → gate de expansión de slash commands (nuevo desde v3.4.0)

Rollout v3 behaviors a los 8 proyectos restantes

Después del periodo de validación de los 4 pilotos (dotforge, cotiza-api-cloud, TRADINGBOT, jira-nbch)
Targets: SOMA, SOMA2, InviSight-iOS, derup, crm, cds-dashboard, openclaw, vault-bot

Sandbox config para proyectos con secretos

TRADINGBOT, derup → habilitar sandbox.enabled con filesystem.denyRead sobre .env

Hook follow-up de v3.4.0

template/hooks/tool-latency.sh — PostToolUse hook que bufferea duration_ms por tool a un archivo, leído por session-report.sh al final de la sesión
Auditoría de stacks por Bash(find:*)/Bash(rm:*) allow rules afectados por el tightening v2.1.113

Cleanup

Redis section redundancy entre python-fastapi y redis
go-api permisos redundantes
forge.md: corregir "zero questions"

Backlog (válido, sin fecha)

Item	Por qué no ahora
Coordinator Mode integration	Gated a `false` en external build. Preparar stack cuando ship
autoDream memory consolidation	Investigar si post-compact output puede alimentar dream
Stacks como plugins independientes	Marketplace sin spec estable
Team mode (`.claude/team.json`)	Fuera de scope para uso personal
CI GitLab template	Sin demanda concreta
`@include` directive evaluation	Investigar si reemplaza modularización manual
Custom compact instructions por stack	Investigar `/compact` con instrucciones específicas
Badge dinámico de audit score	Requiere CI pipeline estable primero
`/forge migrate`	Migración entre versiones mayores. Esperar breaking change real
Hook `prompt` type en block-destructive	Dejar que Claude decida vs regex. Alto costo — evaluar ROI

Descartado

Idea	Razón
npm/npx distribution	Requiere app code, rompe filosofía md+shell
Web UI / dashboard	Fuera de scope, terminal-native
Real-time analytics	Requiere daemon, contradice "no app code"
Stop hook B1 (grep-based)	Genera ruido sin semántica
500+ skills at scale	Calidad > cantidad
Model routing automático en runtime	Over-engineering — reglas explícitas son más predecibles
Auto-escalation por token count	Over-engineering — routing por tipo de tarea, no por tamaño
MCP server self-hosting	dotforge configura clientes, no servers
`/forge export cursor\|windsurf`	Specs de terceros inestables