sourcecode 5.9.31__tar.gz → 5.9.33__tar.gz

{sourcecode-5.9.31 → sourcecode-5.9.33}/.github/workflows/build-windows.yml

@@ -3,6 +3,10 @@ name: Build Windows EXE
 on:
   workflow_dispatch:
 
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   build-windows:
     runs-on: windows-latest

{sourcecode-5.9.31 → sourcecode-5.9.33}/.github/workflows/perf-gate.yml

@@ -29,6 +29,10 @@ concurrency:
   group: perf-gate
   cancel-in-progress: false
 
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   gate:
     runs-on: ubuntu-latest

{sourcecode-5.9.31 → sourcecode-5.9.33}/.github/workflows/windows-battery.yml

@@ -12,6 +12,10 @@ concurrency:
   group: windows-battery-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   battery:
     runs-on: windows-latest

{sourcecode-5.9.31 → sourcecode-5.9.33}/.github/workflows/windows-regression.yml

@@ -10,6 +10,10 @@ on:
 # observe Git Bash rewriting a route argument such as `/owners` to an absolute
 # Windows path.  Keep both the normal Python regression suite and the actual
 # Git Bash invocation on a Windows runner.
+env:
+  SOURCECODE_TELEMETRY: "0"
+  SOURCECODE_TELEMETRY_CONTEXT: "ci"
+
 jobs:
   windows-cli:
     runs-on: windows-latest

{sourcecode-5.9.31 → sourcecode-5.9.33}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [5.9.33] — 2026-09-15
+
+*Patch release keeping `ask --help` responsive on large repositories.*
+
+### Fixed
+
+- Bare `ask --help` no longer scans the current directory while building
+  contextual suggestions. Repository-aware help remains available with
+  `ask <repo> --help`.
+- Informational `--help` and `--version` exits no longer fail because an
+  unrelated `--output` path was not created.
+
+## [5.9.32] — 2026-09-15
+
+*Patch release adding safe, explicit PyPI update notifications and installation.*
+
+### Added
+
+- `ask version` and `ask update --check` report when a newer ASK release exists.
+- `ask update` asks for confirmation; `ask update --yes` is the explicit
+  non-interactive form.
+- MCP agents can use `check_for_updates()` and `update_ask(confirm=true)`.
+- Updates use the active Python interpreter, serialize concurrent installs,
+  verify the installed distribution, and attempt rollback after a failed pip run.
+- Update checks are cached for 24 hours and can be disabled with
+  `SOURCECODE_UPDATE_DISABLED=1`.
+
 ## [5.9.31] — 2026-09-12
 
 *Patch release correcting MCP/CLI telemetry outcomes and the telemetry schema.*

{sourcecode-5.9.31 → sourcecode-5.9.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.31
+Version: 5.9.33
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.31-blue)
+![Version](https://img.shields.io/badge/version-5.9.33-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -290,7 +290,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.31 — and, on a build that has aged,
+ask version                    # ask 5.9.33 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.9.31 → sourcecode-5.9.33}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.31-blue)
+![Version](https://img.shields.io/badge/version-5.9.33-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -241,7 +241,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.31 — and, on a build that has aged,
+ask version                    # ask 5.9.33 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

sourcecode-5.9.33/SPEC-update-notifications.md

@@ -0,0 +1,85 @@
+# Spec: ASK update notifications and opt-in self-update
+
+## Objective
+
+Informar de forma no intrusiva cuando existe una versión más reciente de ASK y
+permitir actualizarla únicamente tras una confirmación explícita. El mismo estado
+debe estar disponible para un agente MCP sin identificar al usuario ni bloquear un
+análisis normal.
+
+## Commands and interfaces
+
+```text
+ask update --check       # consulta y muestra la versión disponible; no instala
+ask update               # consulta; pide confirmación en TTY; instala solo con sí
+ask update --yes         # instala tras la intención explícita del operador
+MCP check_for_updates()  # respuesta estructurada, sin instalar
+MCP update_ask(confirm)  # confirm=false informa; confirm=true instala
+```
+
+La comprobación automática, si se habilita más adelante, tendrá como máximo una
+consulta cacheada al día y nunca se ejecutará durante un comando de análisis.
+
+## Project structure
+
+- `src/sourcecode/update.py` — consulta, comparación, caché y actualización.
+- `src/sourcecode/cli.py` — comandos y confirmación TTY.
+- `src/sourcecode/mcp/server.py` — herramientas MCP estructuradas.
+- `tests/test_update.py` — red, caché, comparación, confirmación e instalación.
+- `docs/update.md` — comportamiento, permisos y recuperación.
+
+## Safety and behavior
+
+- Consultar únicamente el endpoint oficial HTTPS de PyPI:
+  `https://pypi.org/pypi/sourcecode/json`, y aceptar respuestas JSON con versión
+  semántica válida.
+- No ejecutar código descargado directamente: delegar en
+  `sys.executable -m pip install --upgrade sourcecode`.
+- Mostrar versión actual, versión objetivo, intérprete y comando antes de instalar.
+- No actualizar si el entorno es CI, pytest, desarrollo editable o si
+  `SOURCECODE_TELEMETRY_CONTEXT` no es `production`.
+- No usar `sudo`, no modificar archivos del proyecto y no enviar credenciales.
+- Timeout corto, errores silenciosos en la comprobación y errores explícitos en una
+  actualización solicitada.
+- Una sola actualización por entorno a la vez, validación de la distribución
+  instalada y recuperación al intentar restaurar la versión anterior si pip falla.
+- `--yes` solo evita la pregunta; no convierte una comprobación en actualización.
+- Tras instalar, verificar que la versión cargada coincide con la objetivo y sugerir
+  reiniciar procesos MCP persistentes.
+
+## Testing strategy
+
+- Respuestas inválidas, timeout y versiones iguales/no válidas.
+- Caché diaria y ausencia de red en CI/tests.
+- Confirmación no interactiva sin `--yes` no instala.
+- `--yes` ejecuta exactamente el intérprete actual y el paquete `sourcecode`.
+- MCP nunca instala con `confirm=false` y devuelve resultado estructurado.
+- Nunca se muestran ni transmiten rutas, tokens o datos del usuario.
+
+## Boundaries
+
+- Always: pedir consentimiento antes de instalar, usar el intérprete actual y
+  verificar el resultado.
+- Ask first: activar comprobación automática al inicio de comandos de análisis;
+  cambiar el paquete o índice consultado.
+- Never: autoactualizar sin consentimiento, usar `sudo`, ejecutar scripts remotos o
+  actualizar un proceso MCP en caliente.
+- `SOURCECODE_UPDATE_DISABLED=1` desactiva tanto las comprobaciones como las
+  instalaciones solicitadas (útil para políticas corporativas).
+
+## Success criteria
+
+1. Un usuario puede conocer la última versión con `ask update --check`.
+2. `ask update` ofrece actualizar y solo instala tras “sí”.
+3. Un agente puede consultar el estado mediante MCP y solicitar la actualización
+   con `confirm=true`.
+4. CI/tests/desarrollo no generan consultas ni instalaciones.
+5. Los tests cubren todos los casos de seguridad anteriores.
+
+## Open questions
+
+- ¿Debe la notificación automática aparecer al inicio de todos los comandos o solo
+  en `ask version`/`ask update`? Esta especificación propone no interrumpir análisis
+  hasta obtener una decisión explícita.
+- PyPI oficial es el único índice soportado inicialmente. Un índice alternativo
+  requerirá una especificación y decisión separadas.

{sourcecode-5.9.31 → sourcecode-5.9.33}/docs/USER_GUIDE.md

@@ -279,7 +279,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.9.31
+# ask 5.9.33
 ```
 
 Requires Python 3.9+.

sourcecode-5.9.33/docs/investigations/2026-09-15-core-audit.md

@@ -0,0 +1,107 @@
+# Auditoría intensiva del camino crítico de ASK (2026-09-15)
+
+## Repositorios y ground truth
+
+| Repo | SHA auditado | Características |
+|---|---|---|
+| `testing/fullstack-app/spring-boot-server` | `de63350a76b0ad272b43a17d6aa071e5585b904c` | 6 Java, Spring Boot 3.1, Maven, REST/JPA; checkout padre Git |
+| `spring-projects/spring-petclinic` | `818c4136ea971c21674525f9053de0d9c7ad8cfe` | 50 Java, Spring Boot 4.1, Maven/Gradle, MVC/Thymeleaf/JPA |
+| `apache/kafka` | `3eb0b8c1b27d10084a6fee3b787616ddc06bcedc` | 6,188 Java, Gradle, multimódulo, Scala, JAX-RS/Trogdor |
+| `micronaut-projects/micronaut-core` | `09c62d0ed1a51703dab798867218a9a116192ca7` | 5,378 Java, Gradle, JVM/Micronaut, Java/Kotlin/Groovy |
+
+Los tres últimos fueron clones shallow de GitHub sin modificar sus fuentes; Kafka y
+Micronaut se usaron para estresar tamaño y arquitectura. El checkout local contiene
+archivos no versionados del entorno (`.ade`, `memory-bank`, `testdb.mv.db`), que ASK
+reporta honestamente como estado Git sucio.
+
+## Alcance y matriz ejecutada
+
+Se inspeccionaron CLI, `prepare-context`, parser/IR, serializadores `compact` y
+`agent`, Git, caché, MCP, contratos de salida y tests. Para cada repo se ejecutaron
+las salidas compacta y agent, endpoints cuando aplicaba, tres análisis repetidos,
+frío/cálido, y un ciclo modificar → analizar → revertir → analizar. También se
+probaron repositorio vacío, POM roto, Java inválido, Unicode y symlink.
+
+Ground truth independiente: conteo `find`, lectura directa de controladores,
+`ripgrep` de anotaciones, `git log/diff/status`, manifests y SHAs. En el servidor
+local ASK encontró exactamente los 7 mappings REST reales. En Petclinic encontró
+17 rutas; la inspección de controladores confirma 17 mappings literales. Kafka
+expone 44 rutas JAX-RS en Trogdor, que ASK enumera como 44.
+
+## Rendimiento observado
+
+Medianas aproximadas de cuatro ejecuciones de `ask <repo> --compact --format json`
+(primera fría, tres posteriores cálidas; macOS/Python 3.14, caché local):
+
+| Repo | Java | Frío | Cálido (mediana) | Compact bytes | Agent bytes |
+|---|---:|---:|---:|---:|---:|
+| server local | 6 | 0.57 s | 0.40 s | 8,603 | 12,288 |
+| Petclinic | 50 | 0.67 s | 0.40 s | 11,661 | 26,778 |
+| Kafka | 6,188 | 6.02 s | 0.46 s | 14,332 | 39,329 |
+| Micronaut | 5,378 | 4.13 s | 0.56 s | 15,096 | 25,120 |
+
+No es una baseline de memoria ni de otras plataformas. El principal coste frío es
+el escaneo/parsing inicial; la caché reduce el coste posterior de forma material.
+
+## Findings
+
+| ID / severidad / estado | Reproducción y evidencia | Impacto / decisión |
+|---|---|---|
+| CORE-001 / HIGH / CONFIRMED | `ask analyze --since HEAD` no es una invocación válida; `--since` existe en `prepare-context delta`. | La documentación de la tarea usa un nombre conceptual distinto al contrato CLI real. No se cambia retrospectivamente: usar `ask prepare-context delta <repo> --since REF`; añadir alias sería una decisión de API separada. |
+| CORE-002 / MEDIUM / CONFIRMED | `prepare-context delta --since HEAD` publica `git diff --name-only HEAD HEAD` e `includes_uncommitted=false`; una modificación sin commit produce `no_changes`. | Correcto para comparación de refs, peligroso si el agente cree que incluye working tree. El payload lo declara; el bucle de cambios locales debe usar la ruta de análisis con `--git-context`/changed-only. |
+| CORE-003 / MEDIUM / CONFIRMED LIMITATION | Micronaut: 87 controladores aparecen en el inventario, pero `endpoints` devuelve 0 y `coverage.gaps` declara `micronaut: 87 controllers`. | No es un falso cero oculto: la limitación está explícita. ASK no debe usarse como inventario HTTP Micronaut hasta añadir extractor específico. |
+| CORE-004 / LOW / CONFIRMED LIMITATION | Arquitectura de Kafka/Micronaut infiere capas por directorios y emite limitaciones de baja confianza/refutación. | El resultado no presenta la inferencia como certeza y conserva `confidence`/`limitations`. No corregir con heurísticas por repo. |
+| CORE-005 / LOW / CONFIRMED | En el checkout local, archivos no versionados del entorno entran en `uncommitted_files` y hotspots no distinguen intención humana. | Es fiel a Git y no altera la semántica; consumidores deben leer `tree_state` y `scope`. |
+| CORE-006 / LOW / NOT-REPRODUCED | Tres ejecuciones idénticas de Petclinic producen el mismo hash semántico tras quitar clocks/cache metadata. | No hay defecto de determinismo en la muestra. |
+
+No se encontraron defectos CRITICAL/HIGH de corrección en las rutas ejecutadas
+fuera de la incompatibilidad de nombre `analyze --since`. No se modificó código de
+análisis porque las limitaciones observadas ya se publican de manera inequívoca.
+
+## CLI, MCP, compact y agent
+
+`get_agent_context` MCP y `ask <repo> --agent` devolvieron el mismo proyecto,
+frameworks, entry points y señales para Petclinic. MCP añade la envoltura
+`success/data/error`, conservando el contrato interno. Las llamadas consecutivas
+comparten la misma caché y el mismo scope; los errores se estructuran sin traceback.
+
+`--compact` cambia la forma y elimina detalle, pero conserva identidad de proyecto,
+entry points, dependencias, confianza y gaps. No se observaron cifras materiales
+contradictorias respecto a `--agent`; los bytes muestran una reducción clara en
+repos pequeños y grandes. La salida agent puede ser 1.7–2.7× mayor que compacta,
+porque incorpora señales y razones útiles para decisiones del modelo.
+
+## Caché e incrementalidad
+
+La clave incorpora SHA, estado dirty y fingerprint del analizador. En Petclinic:
+
+```text
+cold      served_from_cache=false, fresh
+repetido  served_from_cache=true,  L2_view
+modificar served_from_cache=false, fresh, tree=<sha>+dirty:<hash>
+revertir  served_from_cache=true,  L2_view
+```
+
+No se observó stale-cache, símbolo fantasma ni duplicación en este ciclo. `--since`
+debe interpretarse como comparación de commits/ref; no sustituye la detección de
+cambios no committeados.
+
+## Robustez y seguridad
+
+Repos vacío, POM roto, Java sintácticamente inválido, Unicode y symlink terminaron
+con JSON válido y `rc=0` con gaps/confianza, sin traceback. No se escribieron los
+repositorios auditados. Los límites de salida publican `answer_bounds`; las
+superficies no soportadas se enumeran en `non_coverage`/`coverage.gaps`.
+
+## Veredicto
+
+1. `ask <repo> --agent` es suficientemente fiable para comprensión continua de repos Java/Spring muestreados, siempre leyendo confianza y gaps.
+2. `prepare-context delta --since REF` es fiable para deltas entre refs; no debe tratarse como working-tree delta cuando REF es `HEAD`.
+3. `--compact` conserva hechos centrales y reduce materialmente el output.
+4. `--agent` es claro y estable para un LLM, con límites explícitos.
+5. CLI y MCP son semánticamente equivalentes en la muestra; MCP añade envoltura y límites propios.
+6. No se confirmó stale-cache; la invalidación por estado dirty funcionó.
+7. El cuello de botella principal es el primer escaneo/parsing frío de repos grandes.
+8. El principal riesgo de corrección es interpretar como completa una superficie que ASK declara fuera de cobertura (Micronaut HTTP, servlets y DSLs no soportados).
+9. La siguiente inversión base debería ser un contrato incremental unificado que nombre explícitamente `ref delta` frente a `working-tree delta`, seguido de extractor Micronaut si ese stack es prioritario.
+10. Confiaría en ASK para estructura, dependencias, mappings soportados, cambios Git entre refs y contexto agent; no lo usaría como única fuente de verdad para reflexión, proxies runtime o endpoints de frameworks declarados en `coverage.gaps`.

sourcecode-5.9.33/docs/investigations/2026-09-15-telemetry-audit.md

@@ -0,0 +1,50 @@
+# Auditoría de telemetría ASK — diagnóstico previo (2026-09-15)
+
+Diagnóstico escrito antes de modificar productores, receptor o tests. Revisión local;
+no se ha accedido a la base de producción ni a los logs de Actions. Los números
+históricos son evidencia aportada por el solicitante, no mediciones verificadas aquí.
+
+## Mapa
+
+CLI `cli.py:_get_command_with_preprocessing/_cmd_main` → `telemetry.record`
+→ `TelemetryEvent` → `filters.sanitize` → `transport.send` (hilo daemon por evento,
+sin cola persistente/reintentos) → HTTPS Supabase `functions/telemetry/index.ts`
+→ INSERT `public.telemetry_events` → `sql/telemetry_events.sql` (retención 90 días).
+
+MCP `server.py:FastMCP.Tool.run` → herramienta → `runner.run_command/CliRunner`
+→ wrapper CLI anterior; además `_record_tool_invocation` emite `mcp_tool_invoked`.
+Licensing `license.py:_emit_telemetry` → activation / gate_blocked → mismo recorder.
+`cli.py:telemetry_enable` emite telemetry_enabled. No productor actual de
+command_executed, execution_failed ni telemetry_disabled. El receptor convierte
+nombres desconocidos a command_executed.
+
+## Hallazgos
+
+| Finding / estado | Evidence | Root cause | Impact on analytics | Severity | Proposed fix |
+|---|---|---|---|---|---|
+| CONFIRMED: tests/CI pueden enviar a producción | config.is_enabled devuelve True en CI; test_telemetry_on_by_default_in_ci lo exige; conftest no aísla red; workflows Windows ejecutan pytest/CLI sin exclusión | default-on sin detección ni defensa en transporte | tests cuentan como instalaciones/ejecuciones | P0 | contexto runtime, bloqueo de red sintética, env global suite/workflows |
+| HIGH-CONFIDENCE: ráfagas Windows compatibles con batería | windows-battery ejecuta pytest en runner efímero, varios procesos xdist; endpoint por defecto real | HOME del runner nuevo + UUID por configuración | adquisición inflada | P0 | excluir CI antes de crear ID; no atribuir filas concretas sin logs |
+| CONFIRMED: carrera creando ID | config.get_install_id lee JSON, escribe sin lock, devuelve UUID propio aunque otro proceso haya sobrescrito | read-modify-write no atómico; _save trunca config | múltiples IDs / corrupción | P0 | identidad independiente publicada atómicamente; migrar UUID legado |
+| CONFIRMED: NULL intencional por fallo de persistencia | get_install_id devuelve cadena vacía; sanitize omite install; receptor uuid devuelve null | degradación deliberada a evento sin identidad | días con eventos y cero instalaciones | P0 | no enviar si identidad estable no disponible; validar v2 en receptor |
+| NOT-REPRODUCED: actualizar versión regenera ID | ruta fija ~/.config/sourcecode/config.json, no usa versión/venv | no hay ruta de actualización que regenere | no atribuir rotación a pip sin pruebas | P0 | test de actualización; documentar HOME/volúmenes/config compartidos |
+| CONFIRMED histórico: éxito marcado false | git show 129fd04^:cli.py captura BaseException incluyendo SystemExit(0); investigación 2026-09-11 reproduce MCP | Click termina con SystemExit incluso con éxito | tasa de éxito histórica inválida | P0 | conservar fix 129fd04; versionar contrato; no reparar filas por suposición |
+| CONFIRMED: failed=0 pese a errores | _cmd_main siempre emite execution_completed; ningún productor execution_failed | evento terminal único sin resultado tipado | errores/negativos/excepciones mezclados | P0 | outcome explícito, inicio correlacionado, failed para error real detectado |
+| CONFIRMED: MCP doble dimensión sin correlación | Tool.run emite y CliRunner emite; session global de 8 hex por proceso | sumar eventos duplica acciones; sesión no es llamada ni usuario | engagement inflado | P1 | UUID ejecución, parent, interface mcp; separar herramientas y comandos |
+| CONFIRMED: sesión por proceso importado | telemetry._SESSION inicializado al importar | 32 bits y herencia por fork | colisiones y sesiones indistinguibles | P1 | 128 bits, renovar por PID; documentar proceso MCP persistente |
+| CONFIRMED: licensing ya separado por evento | activate_license emite activation InvalidLicense; gates emiten gate_blocked | agregación success/error_kind sin event mezcla dominios | atribuir incapacidad/churn sin evidencia | P1 | outcome de dominio y excluir licensing de errores de ejecución |
+| CONFIRMED: flags usa allowlist | filters._SAFE_FLAGS y receptor FLAGS descartan valores | protección existente adecuada; comando buscado entre todos los tokens puede tomar un valor como comando | privacidad preservada para flags, dimensión comando incorrecta | P1 | mantener allowlist, usar contexto Click para comando; capacidades semánticas |
+| CONFIRMED: falta versión de schema | v es versión producto; schema sin campo de contrato | cambios de significado no distinguibles | mezcla de generaciones | P1 | schema_version 2, filas anteriores legacy/unknown |
+| CONFIRMED: pérdidas no medibles | transporte daemon sin flush/retry; rate limit 120/min por IP | salida rápida, red, NAT y límites descartan eventos | conteos observados son incompletos | P1 | flush acotado, documentar límite y no inferir crash de inicio huérfano |
+| SUSPECTED: receptor remoto antiguo | investigación previa documenta coerción de mcp_tool_invoked y falta de tool en esquema antiguo | despliegue posiblemente desincronizado | MCP perdido o inserts fallidos | P1 | migración antes de receptor, no afirmar estado remoto |
+
+## Identidad y límites de atribución
+
+La identidad actual pertenece a la configuración del HOME, no al paquete instalado.
+CLI y MCP usan el mismo módulo en el mismo proceso/HOME. pip/pipx/venv no intervienen;
+HOME temporal, borrado de configuración o contenedor sin volumen sí cambian identidad.
+Copiar un HOME/imagen con ID fusiona instalaciones. No hay prueba de qué UUID histórico
+creó qué job. Tests que parchean _CONFIG_FILE generan UUID en tmp_path; otros CLI tests
+usan directamente el HOME del runner. No se han visto fixtures que envíen UUID fijados.
+
+No deducir humano/bot del uso MCP ni del volumen. Contexto production significa
+«sin señales sintéticas detectadas», nunca prueba de persona externa.

{sourcecode-5.9.31 → sourcecode-5.9.33}/docs/privacy.md

@@ -63,7 +63,12 @@ When telemetry is enabled, these fields are sent per command invocation:
 | `success` | `true` | Whether the command succeeded |
 | `error_kind` | `FileNotFoundError` | Exception class name only, no message |
 | `tool` | `get_compact_context` | MCP tool name only, on `mcp_tool_invoked` events (see below) |
-| `session` | `a3f2c1b0` | 8-char random hex, ephemeral, never persisted |
+| `session` | `7f…` | 32-char random hex, process-scoped and never persisted |
+| `schema_version` | `2` | Telemetry contract version, distinct from ASK `v` |
+| `telemetry_context` | `production` | Runtime origin; `test`, `ci`, and `development` are suppressed |
+| `interface` | `cli` / `mcp` | Invocation surface, never a person identifier |
+| `outcome` | `succeeded` | `started`, `succeeded`, `negative`, `expected_error`, `internal_error`, or `cancelled` |
+| `execution_id` | UUID | Per invocation correlation token; `parent_execution_id` links nested MCP CLI calls |
 
 ### Interpreting execution outcomes
 
@@ -105,7 +110,7 @@ File counts are converted to anonymous ranges before sending:
 
 ### Session identifier
 
-The `session` field is an 8-character random hex string generated fresh each time `sourcecode` runs. It is:
+The `session` field is a 32-character random hex string generated fresh for each process (and refreshed after a fork). It is:
 - **Never persisted** to disk
 - **Never reused** across invocations
 - Only useful for correlating multiple events within a single run (e.g., start + completion)
@@ -193,12 +198,22 @@ The first time you run `ask` interactively (not in CI, not piped), you are shown
 
 ---
 
-## CI environments
+## CI, tests, and development environments
 
-Telemetry remains on in CI unless `SOURCECODE_TELEMETRY=0` or `DO_NOT_TRACK=1` is set. CI is detected only to skip the first-run notice, which has no terminal to appear on:
+Production telemetry is suppressed whenever a standard CI marker (`CI`, `GITHUB_ACTIONS`, and similar), pytest, or an explicit `SOURCECODE_TELEMETRY_CONTEXT` of `test`, `ci`, or `development` is present. This happens before an install ID is created and before the transport opens a connection. A deliberate production deployment must run outside these markers; `SOURCECODE_TELEMETRY=1` cannot override the origin guard. The first-run notice is also skipped:
 
 `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS`, `CIRCLECI`, `TRAVIS`, `JENKINS_URL`, `BUILDKITE`, `GITLAB_CI`, `TF_BUILD`, `TEAMCITY_VERSION`, `DRONE`, `SEMAPHORE`
 
+## Contract and analytics limits
+
+Schema 2 is the population used by the product queries. Legacy rows remain
+queryable with unknown origin/outcome and are never retroactively relabelled.
+`install_id` identifies a persisted ASK configuration, not a person: cloned homes
+merge installations and deleted or ephemeral homes create new ones. Counts are
+observed installations and lower bounds on activity, not a count of real users.
+MCP intensity is agentic usage evidence, never evidence that a human or bot initiated
+it. See [telemetry_product_metrics.sql](../supabase/sql/telemetry_product_metrics.sql).
+
 ---
 
 ## Open source auditability

sourcecode-5.9.33/docs/update.md

@@ -0,0 +1,22 @@
+# ASK updates
+
+`ask update --check` consults the official PyPI JSON endpoint and reports the
+installed and latest versions. Results are cached for 24 hours. A normal
+`ask update` asks for confirmation in an interactive terminal; `ask update --yes`
+is the explicit non-interactive form.
+
+The installer runs `sys.executable -m pip install --upgrade sourcecode`, so the
+same Python environment that launched ASK is updated. It never uses `sudo`, runs
+remote scripts, or changes the repository. Persistent MCP servers must be
+restarted after an update.
+
+Checks and installations are suppressed in CI, pytest, editable development
+checkouts, and other non-production telemetry contexts. Network failures leave
+ASK unchanged. The MCP equivalents are `check_for_updates()` and
+`update_ask(confirm=true)`; `confirm=false` only checks status.
+
+Only one update may run for an environment at a time. After pip returns, ASK
+verifies the installed distribution metadata. If installation fails, it attempts
+to restore the previously installed version and reports whether restoration
+succeeded. Set `SOURCECODE_UPDATE_DISABLED=1` to disable update checks and
+installation for managed environments.

{sourcecode-5.9.31 → sourcecode-5.9.33}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "5.9.31"
+version = "5.9.33"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-5.9.31 → sourcecode-5.9.33}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.9.31"
+__version__ = "5.9.33"