charter refresh-suggest never finds telemetry: close writes CHARTER-NN.telemetry.yaml, refresh-suggest looks for NN-slug.telemetry.yaml

[montfort]

Versions: cli-3.43.0, fw-4.42.0 (also present on cli-3.40.0, first observed 2026-07-26)

Summary

straymark charter refresh-suggest reports (missing) for every closed Charter, in any repo that uses the CLI, because the writer and the reader disagree on the telemetry filename.

The heuristic therefore never activates. In our repo it prints Chain length (closed Charters in window): 0 with 29 telemetry files on disk and 7 closed Charters in the chain.

Root cause

Two telemetry_path_for functions that build different names:

cli/src/commands/charter/close.rs:308-321 — writes CHARTER-NN.telemetry.yaml, deliberately stripping the slug:

// Strip optional slug suffix to keep the telemetry filename stable across
// Charter renames: CHARTER-01-foo → CHARTER-01.telemetry.yaml.

cli/src/commands/charter/refresh_suggest.rs:133-138 — reads <file_stem>.telemetry.yaml, where the stem is the Charter's own filename:

/// Charters live at `.straymark/charters/<NN-slug>.md`; telemetry sits next to
/// them as `<NN-slug>.telemetry.yaml` per the convention in charter.rs.
fn telemetry_path_for(_project_root: &Path, charter: &Charter) -> Option<PathBuf> {
    let stem = charter.path.file_stem()?.to_str()?;

So for a Charter at .straymark/charters/22-fundacion-expedientes.md:

• close writes .straymark/charters/CHARTER-22.telemetry.yaml ✅ (exists)
• refresh-suggest looks for .straymark/charters/22-fundacion-expedientes.telemetry.yaml ❌ (never written)

Note the doc comment in refresh_suggest.rs states the <NN-slug> convention as fact — it's the stale one. STRAYMARK.md §10 and §15 document the same stale pattern, so the docs corroborate the reader, not the writer.

Reproduction

Any repo with at least one closed Charter that has telemetry:

$ ls .straymark/charters/*.telemetry.yaml | wc -l
29

$ straymark charter refresh-suggest expedientes

    charter_id                                closed_at         R<N+1>  telemetry
    ----------                                ----------        ------  ---------
    CHARTER-22-fundacion-expedientes          —                      —  (missing)
    CHARTER-23-expedientes-us1                —                      —  (missing)
    CHARTER-24-expedientes-seguimiento        —                      —  (missing)
    ...

  Heuristic
    Chain length (closed Charters in window): 0

  ℹ Chain shorter than 3 closed Charters with telemetry — heuristic not yet meaningful.

Why it matters

The refresh heuristic is precisely the mechanism that detects accumulated spec drift across a Charter chain — the problem CHARTER-CHAIN-EVOLUTION.md was written to address. It has been silently inert since the two names diverged, and the failure mode is indistinguishable from "you don't have enough closed Charters yet", so an adopter reads the message as normal and never suspects a defect. We ran a seven-Charter chain past it without the heuristic ever firing.

Suggested fix

close.rs has the better rule — a filename stable across Charter renames — so align the reader to the writer rather than the reverse: have refresh_suggest.rs derive the name from charter.frontmatter.charter_id the same way close.rs does. Factoring the canonical-name derivation into one shared helper would prevent them drifting apart again.

Falling back to the legacy <NN-slug>.telemetry.yaml when the canonical name is absent would also pick up telemetry written by older CLI versions, if any adopter has that on disk.

STRAYMARK.md §10 and §15 need the same correction — they document the name that is never produced.

Secondary observation

The heuristic block prints two different thresholds for the same condition:

    Threshold for rolling mean:               > 6
  ℹ Chain shorter than 3 closed Charters with telemetry — heuristic not yet meaningful.

> 6 and 3 may well be two distinct gates, but as rendered they read as contradictory. Worth a label that distinguishes them.

---

Reported from ri-ceiba (private adopter repo, ASP.NET Core / Blazor). Tracked there as FU-033.

[montfort]

Confirmado en su totalidad. El diagnóstico es correcto en cada punto, incluida la lectura de cuál de los dos nombres es el bueno. Añado la reproducción sobre un segundo repo y una corrección al alcance de la parte documental.

Reproducido fuera de ri-ceiba

Sentinel tiene 27 telemetrías en disco, todas CHARTER-NN.telemetry.yaml, y sus Charters se llaman NN-slug.md:

$ ls .straymark/charters/*.telemetry.yaml | wc -l
27
$ ls .straymark/charters/*.md | head -1
02-gin-index-sobre-heartbeats-checks-plan-04-f5.md

$ straymark charter refresh-suggest heartbeats
    charter_id                                                closed_at   R<N+1>  telemetry
    CHARTER-02-gin-index-sobre-heartbeats-checks-plan-04-f5    —                —  (missing)

  Heuristic
    Chain length (closed Charters in window): 0

CHARTER-02.telemetry.yaml existe. El lector busca 02-gin-index-sobre-heartbeats-checks-plan-04-f5.telemetry.yaml, que nunca se escribió. No es específico de ri-ceiba: afecta a cualquier repo con Charters cerrados.

La parte documental es más amplia de lo reportado

El patrón obsoleto NN-slug.telemetry.yaml no está solo en STRAYMARK.md §10 y §15. Está en cinco archivos distribuidos:

• dist/STRAYMARK.md (líneas 287 y 385)
• dist/.straymark/00-governance/QUICK-REFERENCE.md — y sus traducciones es y zh-CN
• dist/.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md

Es decir, la documentación corrobora al lector en todos los idiomas. Un adoptante que fuera a verificar el nombre a mano encontraría confirmación del nombre equivocado.

Observación secundaria: confirmada

Los dos umbrales se imprimen tal cual describes, y en la salida de arriba se ve el problema completo: Chain length: 0 con > 6 como umbral de la media móvil y 3 en el mensaje informativo. Son gates distintos, pero renderizados así se leen como contradictorios — y el 0 viene del defecto, no de la realidad de la cadena.

Sobre el modo de fallo

Esto es lo que hace al issue más urgente que su tamaño de arreglo: el mensaje Chain shorter than 3 closed Charters with telemetry — heuristic not yet meaningful es tranquilizador y correcto de forma. Una cadena de siete Charters puede pasar entera sin que nadie sospeche, que es exactamente lo que reportas. El fallo silencioso no está en el cálculo, está en que el diagnóstico de "no aplica todavía" es indistinguible de "está roto".

Plan

1. Un único helper compartido que derive el nombre canónico desde charter_id, usado por close.rs y refresh_suggest.rs, para que no puedan volver a divergir.
2. Fallback al nombre legacy <NN-slug>.telemetry.yaml cuando el canónico no exista, para recoger telemetría escrita por CLIs antiguos.
3. Test que falle si los dos caminos vuelven a producir nombres distintos — la regresión que importa no es el nombre, es la divergencia.
4. Etiquetas distintas para los dos umbrales.
5. Corregir la convención en los cinco archivos, los tres idiomas incluidos.

[montfort]

Arreglado en #417, ya en main — fw-4.43.0 / cli-3.45.0.

Qué se aplicó

Un solo origen para el nombre. canonical_telemetry_name en cli/src/commands/charter/mod.rs, derivado de charter_id con el slug quitado. close.rs y refresh_suggest.rs delegan ahí, así que ya no pueden divergir. Tu lectura de cuál de los dos nombres conservar era la correcta: el que sobrevive a un rename del Charter.

Fallback al nombre legacy, como sugerías: si CHARTER-NN.telemetry.yaml no existe se prueba <NN-slug>.telemetry.yaml. Con una salvedad honesta — esto no está verificado contra un archivo real. No consta ningún adoptante con telemetría bajo el nombre viejo en disco; el test cubre el orden de resolución, no un caso real. Se añadió porque cuesta un exists().

El test que importa no fija el nombre, fija la coincidencia:

let written = canonical_telemetry_path(dir, id);
let read    = resolve_telemetry_path(&charter_path, id);
assert_eq!(written, read);

La regresión a evitar no es el string, es que los dos lados vuelvan a derivarlo por su cuenta.

Los dos umbrales, ahora cada línea dice qué controla:

    Sample size — closed Charters with telemetry: 1 (need 3 to evaluate)
    Refresh trigger — rolling mean must exceed:   6

Verificado en Sentinel

Antes: (missing) en todos los Charters, Chain length: 0, con 27 telemetrías en disco.
Después:

  ● CHARTER-02-gin-index-sobre-heartbeats-checks-plan-04-f5  2026-05-02   1  CHARTER-02.telemetry.yaml
    Sample size — closed Charters with telemetry: 1 (need 3 to evaluate)
    Rolling mean of agent_quality.r_n_plus_one_emergent_count: 1.00

Corrección a mi comentario anterior

Dije que la convención obsoleta estaba en cinco archivos, incluido SPECKIT-CHARTER-BRIDGE.md. Son cuatro: dist/STRAYMARK.md y QUICK-REFERENCE.md en los tres idiomas, más el mensaje que imprime charter amend --merge-into. Mi grep había cruzado NN-slug.md —que es correcto, ese sí es el nombre del Charter— con la palabra "telemetry" en la misma línea. SPECKIT-CHARTER-BRIDGE.md estaba bien.

cargo test: 967 pasan, 0 fallos. Trabajo registrado en AILOG-2026-08-07-001.

Gracias por el reporte — el diagnóstico venía con la causa raíz ya localizada en las dos funciones, lo que dejó la investigación en confirmar el alcance en vez de buscarla.