diff --git a/CHANGELOG.md b/CHANGELOG.md index f19b576..005829f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,28 @@ and this project uses [independent versioning](README.md#versioning) for Framewo --- +## Framework 4.10.0 — Follow-ups backlog pattern (governance docs) + +Documents the follow-ups backlog convention contributed by the Sentinel adopter via [issue #111](https://github.com/StrangeDaysTech/devtrail/issues/111). The pattern was empirically validated in `StrangeDaysTech/sentinel` CHARTER-12 (47 AILOGs accumulated across CHARTER-08 → CHARTER-11). Adopters reaching ~20+ AILOGs benefit from a central registry + per-AILOG drift detection script + agent integration in `CLAUDE.md` / `AGENT.md`. + +This release is **docs only** — no CLI changes, no schema changes, no audit flow changes. Cristalization as a `devtrail followups` subcommand is deferred until a second adopter validates the pattern. + +### Added (Framework) + +- **NEW governance pattern document** `FOLLOW-UPS-BACKLOG-PATTERN.md` describing the reproducible convention: registry shape (`.devtrail/follow-ups-backlog.md` with `fully_extracted_ailogs` frontmatter), 5 buckets (`ready` / `time-triggered` / `charter-triggered` / `phase-blocked` / `operational`), per-entry schema (FU-NNN / Origin / Status / Trigger / Destination / Cost / Notes), drift detection script (3 modes: default / `--apply` / `--scan-all`), agent integration block, adoption walkthrough, reference implementation in Sentinel CHARTER-12 (PRs #53/#54), and open questions (bucket heuristic, schema validation, audit-cycle integration, cristalization path). +- **Pointers** added in `AGENT-RULES.md` (new "Patterns" section) and `QUICK-REFERENCE.md` (new "Patterns" table) referencing the new pattern document. +- **Translations** to ES and zh-CN under `dist/.devtrail/00-governance/i18n/{es,zh-CN}/FOLLOW-UPS-BACKLOG-PATTERN.md`. + +### Changed (Framework) + +- Footer version bumps from `v4.9.0` to `v4.10.0` across governance docs (EN + ES + zh-CN) and version-table references in adopter docs. + +### Status + +The pattern is **v0** — proven in N=1 domain (Sentinel). It may evolve into a CLI helper after a second-domain validation. Adopters who implement it now follow the documented convention; their local script + registry is fully portable and survives a future cristalization unchanged. + +--- + ## Framework 4.9.0 / CLI 3.10.0 — Audit v1: zero copy/paste flow with auditor-side CLI tool use Closes the four axes reported in [issue #102](https://github.com/StrangeDaysTech/devtrail/issues/102) by Sentinel during its first primary-adopter run of the v0 audit-skills (CHARTER-07 of CommsHub Etapa 2). The release is **one integrated iteration** rather than four separate patches — Sentinel re-runs CHARTER-07 once after this lands, with the full v1 flow, instead of multiple times against partial fixes. diff --git a/README.md b/README.md index 8643fff..e04a787 100644 --- a/README.md +++ b/README.md @@ -259,7 +259,7 @@ DevTrail uses independent version tags for each component: | Component | Tag prefix | Example | Includes | |-----------|-----------|---------|----------| -| Framework | `fw-` | `fw-4.9.0` | Templates (12 types), governance, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.10.0` | Templates (12 types), governance, directives, Charter template + schema | | CLI | `cli-` | `cli-3.10.0` | The `devtrail` binary | Check installed versions with `devtrail status` or `devtrail about`. @@ -292,7 +292,7 @@ See [CLI Reference](https://github.com/StrangeDaysTech/devtrail/blob/main/docs/a ```bash # Download the latest framework release ZIP from GitHub # Go to https://github.com/StrangeDaysTech/devtrail/releases -# and download the latest fw-* release (e.g., fw-4.9.0) +# and download the latest fw-* release (e.g., fw-4.10.0) # Extract and copy to your project unzip devtrail-fw-*.zip -d your-project/ diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md index 9040daf..250d374 100644 --- a/dist/.devtrail/00-governance/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/AGENT-RULES.md @@ -351,4 +351,10 @@ These are heuristics, not rigid rules — you are close to the context, refine t --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +## Patterns + +When a project accumulates a high volume of AILOGs across multiple Charters and follow-ups become hard to track, see [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) for a reproducible convention (central registry + drift detection script + agent integration). Adopters at ~20+ AILOGs benefit; below that threshold the per-AILOG `§Follow-ups` convention alone is sufficient. + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md index 72df75e..30fc2e8 100644 --- a/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate: --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md index a04e183..0857917 100644 --- a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md @@ -307,4 +307,4 @@ See also [ADR-2025-01-20-001] for architectural context. --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.devtrail/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md new file mode 100644 index 0000000..5ee0618 --- /dev/null +++ b/dist/.devtrail/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -0,0 +1,189 @@ +# Follow-ups Backlog Pattern - DevTrail + +> Reproducible convention for managing accumulated `§Follow-ups` and `R (new, not in Charter)` entries across many AILOGs and Charters. + +**Languages**: English | [Español](i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md) | [简体中文](i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md) + +--- + +## Status + +**v0 — proven in N=1 domain** (`StrangeDaysTech/sentinel` CHARTER-12, 2026-05-06). + +This is a **convention**, not a CLI feature. Adopters reproduce it locally with markdown + a portable bash script. The pattern may evolve into a `devtrail followups` subcommand once a second adopter validates it (see [Open questions](#open-questions)). + +--- + +## When this pattern applies + +DevTrail's per-AILOG `§Follow-ups` convention works at write time — when an AILOG is created, the implementer documents what is deferred to subsequent Charters or operational triggers. That works fine until the cumulative list grows past what an operator can scan from memory. + +Adopt this pattern when **any** of these conditions hold: + +- The project has accumulated **~20 or more AILOGs** with non-trivial `§Follow-ups` sections. +- Operators repeatedly ask agents to "list what's pending across the project" and the answer requires a multi-file scan. +- A "do this when X arrives" follow-up was almost lost because the originating AILOG was never re-read after X arrived. +- A Charter retrospective surfaces follow-ups that should have been classified as `closed` weeks earlier but were never indexed. + +Below that volume, the per-AILOG convention alone is sufficient — adopting this pattern early adds maintenance overhead without payoff. + +--- + +## Shape + +### Registry file + +Single markdown file at the canonical path: + +``` +.devtrail/follow-ups-backlog.md +``` + +### Frontmatter (YAML) + +```yaml +--- +last_scan: 2026-05-06 +schema_version: v0 +buckets: + - ready + - time-triggered + - charter-triggered + - phase-blocked + - operational +fully_extracted_ailogs: + - AILOG-2026-04-11-001 + - AILOG-2026-04-12-001 + # ... one entry per AILOG whose follow-ups have been processed +--- +``` + +The `fully_extracted_ailogs` list is the **load-bearing metadata** for drift detection. Every AILOG whose `§Follow-ups` and `R` entries have been transferred into the registry (or explicitly classified as superseded) belongs in this list. Drift detection compares this list against AILOGs that have follow-up content in the repo. + +### Buckets + +Five buckets organize entries by trigger type: + +- `ready` — actionable now, no dependency on external trigger. +- `time-triggered` — calendar-based trigger (audit cycle, periodic review). +- `charter-triggered` — gated on a future Charter that touches the relevant area. +- `phase-blocked` — gated on a future component or phase that does not yet exist. +- `operational` — manual operator decision or external system action. + +### Entry schema + +Each entry inside a bucket follows this shape: + +```markdown +### FU-NNN — +- **Origin**: AILOG-NNNN-NN-NN-NNN +- **Status**: open | in-progress | closed | superseded +- **Trigger**: ready | | when | +- **Destination**: +- **Cost**: +- **Notes**: +``` + +`FU-NNN` is monotonically increasing across the registry's lifetime; do not renumber when entries close. + +### Status vocabulary + +- `open` — pending, not yet acted on. +- `in-progress` — a Charter has been declared or is executing that addresses this entry. +- `closed` — entry resolved (Charter merged, operational task done, time elapsed and reviewed). +- `superseded` — addressed by other work that did not reference this entry directly. + +Closed and superseded entries stay in the file (auditable history). Operators may move them to a `## Bucket: closed` section at the bottom for visual decluttering, but they are never deleted. + +--- + +## Drift detection + +A small bash script is the verification layer that keeps the registry in sync with new AILOGs. The script lives in the adopter's repo (suggested path: `scripts/check-followups-drift.sh`) and has three modes. + +### Modes + +- **Default** — scan AILOGs modified in `git diff origin/main..HEAD` (with `HEAD~1..HEAD` fallback). Warn on any AILOG with `§Follow-ups` / `R (new)` content that is not in `fully_extracted_ailogs`. Exit 1 on drift. +- **`--apply`** — same scan, but auto-append new entries under `## Bucket: ready` with auto-generated `FU-NNN` ids and append the AILOG id to `fully_extracted_ailogs`. The operator reclassifies into the correct bucket later. +- **`--scan-all`** — scan every AILOG in the project (periodic full sweep). + +### Per-AILOG vs per-bullet granularity + +Tracking is **per-AILOG**, not per-bullet. An AILOG is either fully extracted (its id is in `fully_extracted_ailogs` — trust the registry) or it is not (extract everything). Per-bullet matching would require fingerprinting (text hashing or fuzzy comparison), which produces false positives whenever a registry entry paraphrases the AILOG bullet — and curated entries always paraphrase. + +The cost of per-AILOG granularity: when a follow-up is added to an already-extracted AILOG post-Charter close, drift detection misses it. The remediation is operator-driven — manually remove the AILOG from `fully_extracted_ailogs` and re-run with `--apply`. This trade-off is intentional for v0 because most AILOGs are write-once after Charter close. + +### Script template + +A reference implementation (~290 lines of POSIX bash) is in `StrangeDaysTech/sentinel` at `scripts/check-followups-drift.sh`. Copy it into your repo and adjust the constants at the top: + +```bash +BACKLOG_FILE=".devtrail/follow-ups-backlog.md" +AILOG_DIR=".devtrail/07-ai-audit/agent-logs" +``` + +The script uses `awk` and `grep` only — no jq, no yq, no heavyweight dependencies. Portable across Linux and macOS. + +--- + +## Agent integration + +The agent (Claude / Gemini / etc.) becomes the primary maintainer of the registry. Add to your `CLAUDE.md` / `AGENT.md`: + +```markdown +## Follow-ups backlog + +- **Session start**: glance at `.devtrail/follow-ups-backlog.md` to know what is pending across the project. +- **Pre-commit checklist**: created or modified any AILOG with `## Follow-ups` or `R (new, not in Charter)` entries? → run `scripts/check-followups-drift.sh --apply` to extend the backlog in the same commit. +- **Post-Charter close**: review entries the Charter resolved; mark them `closed` (with the closing Charter id in `Notes`) or `superseded`. +``` + +This makes the agent the maintainer, the script the verification layer, and the operator the periodic reviewer (re-bucketing, marking closed, pruning superseded). + +--- + +## Adoption walkthrough + +For an adopter starting fresh: + +1. Create `.devtrail/follow-ups-backlog.md` with the frontmatter above (empty `fully_extracted_ailogs:` list initially) and the five `## Bucket: ` headers. +2. Copy the reference script from `StrangeDaysTech/sentinel` to `scripts/check-followups-drift.sh`. Adjust `AILOG_DIR` if your AILOGs live elsewhere. +3. Run `scripts/check-followups-drift.sh --scan-all --apply` to seed the registry from existing AILOGs. +4. Reclassify the auto-generated `## Bucket: ready` entries into the correct buckets manually. This is one-time triage, typically 30-60 min for a backlog of ~50 entries. +5. Add the agent integration block to `CLAUDE.md` / `AGENT.md`. +6. Optionally wire `scripts/check-followups-drift.sh` into a pre-commit hook for hard enforcement. + +For an adopter migrating from ad-hoc tracking: the same flow, but step 4 may require deciding which entries are already `closed` or `superseded` — that classification is what makes the registry useful. + +--- + +## Reference implementation + +`StrangeDaysTech/sentinel` CHARTER-12, merged 2026-05-06: + +- Implementation PR: [sentinel#53](https://github.com/StrangeDaysTech/sentinel/pull/53) (registry + script + CLAUDE.md additions). +- Close-out PR: [sentinel#54](https://github.com/StrangeDaysTech/sentinel/pull/54) (post-merge verification + Charter close). + +Empirical context: 47 entries seeded from CHARTER-08 → CHARTER-11 retrospective (~30 min of multi-agent triage). The chain demonstrated the gap that motivated the pattern — without the registry, the operator could not see "what is pending across the project" without re-classifying each Charter's follow-ups in isolation. With the registry, session-start glance is one file read. + +--- + +## Open questions + +These are not resolved in v0. Future revisions of this pattern, or a CLI helper, may address them: + +- **Bucket classification heuristic**. Today `--apply` dumps every new entry into `## Bucket: ready`; the operator reclassifies manually. A heuristic using AILOG `tags` and Charter `effort_estimate` could suggest a bucket automatically. +- **Schema validation**. The registry follows a tacit schema; no `.devtrail/schemas/follow-ups-backlog.schema.v0.json` exists yet. Validation today is human review. +- **Integration with the audit cycle**. When `devtrail charter audit --merge-reports` produces real-debt findings that are not remediated atomically pre-close, those findings live only in `.devtrail/audits//review.md`. They do not auto-flow into the central registry. Surfacing them automatically would close a known gap. +- **`closed` vs `superseded` semantics**. Today the difference is whether the resolving work explicitly referenced the entry. A stricter convention may emerge. +- **Cristalization as `devtrail followups` CLI**. Once a second adopter validates the pattern, the framework may ship a subcommand mirroring the existing `devtrail charter` trio: `list` / `close` / `drift`. Adopters at v0 (this pattern) migrate by deleting their local script and switching the agent instruction. + +--- + +## Credits + +Contributed via [issue #111](https://github.com/StrangeDaysTech/devtrail/issues/111) by the Sentinel adopter. Empirical foundation: CHARTER-08 → CHARTER-11 chain in `StrangeDaysTech/sentinel`. Author: Claude Opus 4.7 on behalf of operator José Villaseñor Montfort. + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/QUICK-REFERENCE.md index f0a33c6..54d362a 100644 --- a/dist/.devtrail/00-governance/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/QUICK-REFERENCE.md @@ -219,4 +219,12 @@ Mark `review_required: true` when: --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +## Patterns + +| Pattern | Document | +|---------|----------| +| Follow-ups backlog (central registry + drift detection) *(fw-4.10.0+)* | [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) | + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md index 79035da..adae663 100644 --- a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md @@ -351,4 +351,10 @@ Son heurísticas, no reglas rígidas — estás cerca del contexto, afínalas co --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +## Patrones + +Cuando un proyecto acumula un volumen alto de AILOGs a lo largo de múltiples Charters y los follow-ups se vuelven difíciles de rastrear, ver [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) para una convención reproducible (registro central + script de detección de drift + integración con agentes). Los adopters con ~20+ AILOGs se benefician; por debajo de ese umbral la convención per-AILOG `§Follow-ups` por sí sola es suficiente. + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md index 4fdb44d..1443295 100644 --- a/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar: --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md index 8b52047..8ff0ae5 100644 --- a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -300,4 +300,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico. --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.devtrail/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md new file mode 100644 index 0000000..4736a66 --- /dev/null +++ b/dist/.devtrail/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -0,0 +1,189 @@ +# Patrón de Backlog de Follow-ups - DevTrail + +> Convención reproducible para gestionar entradas acumuladas de `§Follow-ups` y `R (new, not in Charter)` a lo largo de muchos AILOGs y Charters. + +**Idiomas**: [English](../../FOLLOW-UPS-BACKLOG-PATTERN.md) | Español | [简体中文](../zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md) + +--- + +## Estado + +**v0 — validado en N=1 dominio** (`StrangeDaysTech/sentinel` CHARTER-12, 2026-05-06). + +Esto es una **convención**, no una funcionalidad del CLI. Los adopters la reproducen localmente con markdown + un script bash portable. El patrón puede evolucionar a un subcomando `devtrail followups` una vez que un segundo adopter lo valide (ver [Preguntas abiertas](#preguntas-abiertas)). + +--- + +## Cuándo aplica este patrón + +La convención per-AILOG `§Follow-ups` de DevTrail funciona en tiempo de escritura — cuando se crea un AILOG, el implementador documenta lo que se difiere a Charters subsiguientes o triggers operativos. Eso funciona bien hasta que la lista acumulada crece más allá de lo que un operador puede escanear de memoria. + +Adopta este patrón cuando se cumpla **cualquiera** de estas condiciones: + +- El proyecto ha acumulado **~20 o más AILOGs** con secciones `§Follow-ups` no triviales. +- Los operadores piden repetidamente a los agentes "lista qué está pendiente en el proyecto" y la respuesta requiere un escaneo multi-archivo. +- Un follow-up de tipo "haz esto cuando llegue X" estuvo a punto de perderse porque el AILOG originador nunca fue releído después de que llegó X. +- Una retrospectiva de Charter aflora follow-ups que deberían haber sido clasificados como `closed` semanas antes pero nunca fueron indexados. + +Por debajo de ese volumen, la convención per-AILOG por sí sola es suficiente — adoptar este patrón temprano agrega overhead de mantenimiento sin retorno. + +--- + +## Forma + +### Archivo de registro + +Único archivo markdown en la ruta canónica: + +``` +.devtrail/follow-ups-backlog.md +``` + +### Frontmatter (YAML) + +```yaml +--- +last_scan: 2026-05-06 +schema_version: v0 +buckets: + - ready + - time-triggered + - charter-triggered + - phase-blocked + - operational +fully_extracted_ailogs: + - AILOG-2026-04-11-001 + - AILOG-2026-04-12-001 + # ... una entrada por cada AILOG cuyos follow-ups han sido procesados +--- +``` + +La lista `fully_extracted_ailogs` es el **metadato cargante** para la detección de drift. Todo AILOG cuyas entradas de `§Follow-ups` y `R` han sido transferidas al registro (o explícitamente clasificadas como superseded) pertenece a esta lista. La detección de drift compara esta lista contra los AILOGs que tienen contenido de follow-ups en el repo. + +### Buckets + +Cinco buckets organizan las entradas por tipo de trigger: + +- `ready` — accionable ahora, sin dependencia de trigger externo. +- `time-triggered` — trigger basado en calendario (ciclo de auditoría, revisión periódica). +- `charter-triggered` — bloqueado por un Charter futuro que toque el área relevante. +- `phase-blocked` — bloqueado por un componente o fase futura que aún no existe. +- `operational` — decisión manual del operador o acción de sistema externo. + +### Esquema de entrada + +Cada entrada dentro de un bucket sigue esta forma: + +```markdown +### FU-NNN — +- **Origin**: AILOG-NNNN-NN-NN-NNN +- **Status**: open | in-progress | closed | superseded +- **Trigger**: ready | | when | +- **Destination**: +- **Cost**: +- **Notes**: +``` + +`FU-NNN` es monotónicamente creciente a lo largo de la vida del registro; no se renumera cuando las entradas se cierran. + +### Vocabulario de status + +- `open` — pendiente, sin acción aún. +- `in-progress` — un Charter ha sido declarado o está en ejecución para atender esta entrada. +- `closed` — entrada resuelta (Charter mergeado, tarea operativa hecha, tiempo transcurrido y revisado). +- `superseded` — atendida por otro trabajo que no referenció esta entrada directamente. + +Las entradas closed y superseded permanecen en el archivo (historia auditable). Los operadores pueden moverlas a una sección `## Bucket: closed` al final para limpieza visual, pero nunca se eliminan. + +--- + +## Detección de drift + +Un pequeño script bash es la capa de verificación que mantiene el registro sincronizado con nuevos AILOGs. El script vive en el repo del adopter (ruta sugerida: `scripts/check-followups-drift.sh`) y tiene tres modos. + +### Modos + +- **Default** — escanea AILOGs modificados en `git diff origin/main..HEAD` (con fallback a `HEAD~1..HEAD`). Avisa sobre cualquier AILOG con contenido `§Follow-ups` / `R (new)` que no esté en `fully_extracted_ailogs`. Sale con 1 si hay drift. +- **`--apply`** — mismo escaneo, pero auto-agrega nuevas entradas bajo `## Bucket: ready` con ids `FU-NNN` auto-generados y agrega el id del AILOG a `fully_extracted_ailogs`. El operador reclasifica al bucket correcto después. +- **`--scan-all`** — escanea cada AILOG en el proyecto (barrido completo periódico). + +### Granularidad per-AILOG vs per-bullet + +El tracking es **per-AILOG**, no per-bullet. Un AILOG está totalmente extraído (su id está en `fully_extracted_ailogs` — confiar en el registro) o no lo está (extraer todo). El matching per-bullet requeriría fingerprinting (hashing de texto o comparación fuzzy), que produce falsos positivos cada vez que una entrada del registro parafrasea el bullet del AILOG — y las entradas curadas siempre parafrasean. + +El costo de la granularidad per-AILOG: cuando se agrega un follow-up a un AILOG ya extraído tras el cierre del Charter, la detección de drift no lo detecta. La remediación es manual del operador — quitar el AILOG de `fully_extracted_ailogs` y re-correr con `--apply`. Este trade-off es intencional para v0 porque la mayoría de AILOGs son write-once tras el cierre del Charter. + +### Plantilla de script + +Una implementación de referencia (~290 líneas de bash POSIX) está en `StrangeDaysTech/sentinel` en `scripts/check-followups-drift.sh`. Cópiala a tu repo y ajusta las constantes al inicio: + +```bash +BACKLOG_FILE=".devtrail/follow-ups-backlog.md" +AILOG_DIR=".devtrail/07-ai-audit/agent-logs" +``` + +El script usa solo `awk` y `grep` — sin jq, sin yq, sin dependencias pesadas. Portable entre Linux y macOS. + +--- + +## Integración con agentes + +El agente (Claude / Gemini / etc.) se vuelve el mantenedor primario del registro. Agrega a tu `CLAUDE.md` / `AGENT.md`: + +```markdown +## Backlog de follow-ups + +- **Inicio de sesión**: revisar `.devtrail/follow-ups-backlog.md` para saber qué está pendiente en el proyecto. +- **Checklist pre-commit**: ¿creaste o modificaste algún AILOG con entradas `## Follow-ups` o `R (new, not in Charter)`? → ejecuta `scripts/check-followups-drift.sh --apply` para extender el backlog en el mismo commit. +- **Post-cierre de Charter**: revisar entradas que el Charter resolvió; marcarlas `closed` (con el id del Charter de cierre en `Notes`) o `superseded`. +``` + +Esto hace al agente el mantenedor, al script la capa de verificación, y al operador el revisor periódico (re-bucketing, marcar closed, podar superseded). + +--- + +## Walkthrough de adopción + +Para un adopter empezando desde cero: + +1. Crear `.devtrail/follow-ups-backlog.md` con el frontmatter de arriba (lista `fully_extracted_ailogs:` vacía inicialmente) y los cinco headers `## Bucket: `. +2. Copiar el script de referencia desde `StrangeDaysTech/sentinel` a `scripts/check-followups-drift.sh`. Ajustar `AILOG_DIR` si tus AILOGs viven en otro lado. +3. Ejecutar `scripts/check-followups-drift.sh --scan-all --apply` para sembrar el registro desde AILOGs existentes. +4. Reclasificar manualmente las entradas auto-generadas en `## Bucket: ready` a los buckets correctos. Esto es triage one-time, típicamente 30-60 min para un backlog de ~50 entradas. +5. Agregar el bloque de integración con agentes a `CLAUDE.md` / `AGENT.md`. +6. Opcionalmente conectar `scripts/check-followups-drift.sh` a un pre-commit hook para enforcement duro. + +Para un adopter migrando desde tracking ad-hoc: el mismo flujo, pero el paso 4 puede requerir decidir qué entradas ya están `closed` o `superseded` — esa clasificación es lo que hace al registro útil. + +--- + +## Implementación de referencia + +`StrangeDaysTech/sentinel` CHARTER-12, mergeado 2026-05-06: + +- PR de implementación: [sentinel#53](https://github.com/StrangeDaysTech/sentinel/pull/53) (registro + script + adiciones a CLAUDE.md). +- PR de cierre: [sentinel#54](https://github.com/StrangeDaysTech/sentinel/pull/54) (verificación post-merge + cierre del Charter). + +Contexto empírico: 47 entradas sembradas desde la retrospectiva CHARTER-08 → CHARTER-11 (~30 min de triage multi-agente). La cadena demostró el gap que motivó el patrón — sin el registro, el operador no podía ver "qué está pendiente en el proyecto" sin reclasificar los follow-ups de cada Charter en aislamiento. Con el registro, la revisión de inicio de sesión es una sola lectura de archivo. + +--- + +## Preguntas abiertas + +Estas no se resuelven en v0. Revisiones futuras de este patrón, o un helper CLI, pueden atenderlas: + +- **Heurística de clasificación de bucket**. Hoy `--apply` vuelca cada entrada nueva a `## Bucket: ready`; el operador reclasifica manualmente. Una heurística usando `tags` del AILOG y `effort_estimate` del Charter podría sugerir un bucket automáticamente. +- **Validación de schema**. El registro sigue un esquema tácito; aún no existe `.devtrail/schemas/follow-ups-backlog.schema.v0.json`. La validación hoy es revisión humana. +- **Integración con el ciclo de auditoría**. Cuando `devtrail charter audit --merge-reports` produce findings de deuda real que no son remediados atómicamente pre-cierre, esos findings viven solo en `.devtrail/audits//review.md`. No fluyen automáticamente al registro central. Aflorarlos automáticamente cerraría un gap conocido. +- **Semántica `closed` vs `superseded`**. Hoy la diferencia es si el trabajo de resolución referenció explícitamente la entrada. Una convención más estricta puede emerger. +- **Cristalización como CLI `devtrail followups`**. Una vez que un segundo adopter valide el patrón, el framework puede shippear un subcomando que espeje al trío existente `devtrail charter`: `list` / `close` / `drift`. Los adopters en v0 (este patrón) migran borrando su script local y cambiando la instrucción del agente. + +--- + +## Créditos + +Contribuido vía [issue #111](https://github.com/StrangeDaysTech/devtrail/issues/111) por el adopter Sentinel. Fundamento empírico: cadena CHARTER-08 → CHARTER-11 en `StrangeDaysTech/sentinel`. Autor: Claude Opus 4.7 a nombre del operador José Villaseñor Montfort. + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md index de64ac6..e7fa0f6 100644 --- a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md @@ -194,4 +194,12 @@ Marcar `review_required: true` cuando: --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +## Patrones + +| Patrón | Documento | +|--------|-----------| +| Backlog de follow-ups (registro central + detección de drift) *(fw-4.10.0+)* | [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) | + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md index 6a59058..d6e8b02 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md @@ -346,4 +346,10 @@ confidence: high | medium | low --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +## 模式 + +当项目在多个 Charter 之间累积大量 AILOG 且 follow-ups 难以跟踪时,参见 [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) 了解可复制的约定(中央注册表 + drift 检测脚本 + 代理集成)。约 20+ AILOG 的 adopter 会受益;低于该阈值时,仅 per-AILOG 的 `§Follow-ups` 约定就足够了。 + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md index b454c97..51a8a4a 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Rel(api, db, "Reads/Writes", "SQL") --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md index 685c09b..67c85b1 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md @@ -299,4 +299,4 @@ review_outcome: approved # approved | revisions_requested | rejec --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.devtrail/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md new file mode 100644 index 0000000..aee7d72 --- /dev/null +++ b/dist/.devtrail/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -0,0 +1,189 @@ +# Follow-ups Backlog 模式 - DevTrail + +> 用于跨多个 AILOG 和 Charter 管理累积的 `§Follow-ups` 与 `R (new, not in Charter)` 条目的可复制约定。 + +**语言**: [English](../../FOLLOW-UPS-BACKLOG-PATTERN.md) | [Español](../es/FOLLOW-UPS-BACKLOG-PATTERN.md) | 简体中文 + +--- + +## 状态 + +**v0 — 在 N=1 域中已验证**（`StrangeDaysTech/sentinel` CHARTER-12,2026-05-06）。 + +这是一个**约定**,不是 CLI 功能。Adopter 使用 markdown + 一个可移植的 bash 脚本在本地复制此模式。在第二个 adopter 验证后,该模式可能演变为 `devtrail followups` 子命令(参见[未决问题](#未决问题))。 + +--- + +## 何时适用此模式 + +DevTrail 的 per-AILOG `§Follow-ups` 约定在写入时有效 — 创建 AILOG 时,实施者记录推迟到后续 Charter 或操作触发器的内容。在累积列表超出操作员可凭记忆扫描范围之前,这种方式都能正常工作。 + +当满足**任一**以下条件时,采用此模式: + +- 项目已累积 **约 20 个或更多 AILOG**,带有非平凡的 `§Follow-ups` 部分。 +- 操作员反复要求代理"列出项目中所有待处理事项",答案需要多文件扫描。 +- 一个"当 X 到来时执行"的 follow-up 几乎丢失,因为在 X 到来后从未重读过原始 AILOG。 +- Charter 回顾揭示出本应在数周前被分类为 `closed`、但从未被索引的 follow-ups。 + +低于此规模时,仅 per-AILOG 约定就足够了 — 过早采用此模式只会增加维护开销而无回报。 + +--- + +## 形式 + +### 注册表文件 + +规范路径下的单个 markdown 文件: + +``` +.devtrail/follow-ups-backlog.md +``` + +### Frontmatter (YAML) + +```yaml +--- +last_scan: 2026-05-06 +schema_version: v0 +buckets: + - ready + - time-triggered + - charter-triggered + - phase-blocked + - operational +fully_extracted_ailogs: + - AILOG-2026-04-11-001 + - AILOG-2026-04-12-001 + # ... 每个 follow-ups 已被处理的 AILOG 一个条目 +--- +``` + +`fully_extracted_ailogs` 列表是 drift 检测的**承重元数据**。所有 `§Follow-ups` 和 `R` 条目已被转移到注册表(或被显式分类为 superseded)的 AILOG 都属于此列表。Drift 检测将此列表与 repo 中具有 follow-up 内容的 AILOG 进行比对。 + +### Buckets + +五个 bucket 按触发类型组织条目: + +- `ready` — 现在可执行,无外部触发器依赖。 +- `time-triggered` — 基于日历的触发器(审计周期、周期性审查)。 +- `charter-triggered` — 由触及相关领域的未来 Charter 阻塞。 +- `phase-blocked` — 由尚不存在的未来组件或阶段阻塞。 +- `operational` — 操作员手动决策或外部系统操作。 + +### 条目 schema + +bucket 内的每个条目遵循以下形式: + +```markdown +### FU-NNN — <简短描述> +- **Origin**: AILOG-NNNN-NN-NN-NNN <指向源部分的指针> +- **Status**: open | in-progress | closed | superseded +- **Trigger**: ready | <日历日期> | when | <其他> +- **Destination**: +- **Cost**: <工作量估计> +- **Notes**: <自由格式上下文> +``` + +`FU-NNN` 在注册表整个生命周期内单调递增;条目关闭时不重新编号。 + +### Status 词汇表 + +- `open` — 待处理,尚未采取行动。 +- `in-progress` — 已声明或正在执行的 Charter 处理此条目。 +- `closed` — 条目已解决(Charter 已合并、操作任务已完成、时间已过且已审查)。 +- `superseded` — 由其他工作处理,该工作未直接引用此条目。 + +closed 和 superseded 条目保留在文件中(可审计的历史)。操作员可以将它们移到底部的 `## Bucket: closed` 部分以进行视觉整理,但绝不删除。 + +--- + +## Drift 检测 + +一个小的 bash 脚本是验证层,使注册表与新 AILOG 保持同步。该脚本位于 adopter 的 repo 中(建议路径:`scripts/check-followups-drift.sh`),有三种模式。 + +### 模式 + +- **默认** — 扫描 `git diff origin/main..HEAD`(回退到 `HEAD~1..HEAD`)中修改的 AILOG。对任何具有 `§Follow-ups` / `R (new)` 内容但不在 `fully_extracted_ailogs` 中的 AILOG 发出警告。drift 时退出 1。 +- **`--apply`** — 相同的扫描,但自动在 `## Bucket: ready` 下追加新条目,使用自动生成的 `FU-NNN` id,并将 AILOG id 追加到 `fully_extracted_ailogs`。操作员稍后将其重新分类到正确的 bucket。 +- **`--scan-all`** — 扫描项目中的每个 AILOG(周期性完整扫描)。 + +### Per-AILOG 与 per-bullet 粒度 + +跟踪是 **per-AILOG**,而非 per-bullet。AILOG 要么被完全提取(其 id 在 `fully_extracted_ailogs` 中 — 信任注册表),要么未被提取(提取所有内容)。Per-bullet 匹配将需要指纹识别(文本哈希或模糊比较),每当注册表条目对 AILOG 的 bullet 进行改写时,这都会产生误报 — 而经过整理的条目总是会改写。 + +Per-AILOG 粒度的成本:当在 Charter 关闭后向已提取的 AILOG 添加 follow-up 时,drift 检测无法发现。修复由操作员驱动 — 手动从 `fully_extracted_ailogs` 中移除该 AILOG 并使用 `--apply` 重新运行。这种权衡对 v0 是有意为之,因为大多数 AILOG 在 Charter 关闭后是 write-once。 + +### 脚本模板 + +参考实现(约 290 行 POSIX bash)位于 `StrangeDaysTech/sentinel` 的 `scripts/check-followups-drift.sh`。将其复制到你的 repo 并调整顶部常量: + +```bash +BACKLOG_FILE=".devtrail/follow-ups-backlog.md" +AILOG_DIR=".devtrail/07-ai-audit/agent-logs" +``` + +脚本仅使用 `awk` 和 `grep` — 没有 jq、yq 或重型依赖。在 Linux 和 macOS 之间可移植。 + +--- + +## 代理集成 + +代理(Claude / Gemini 等)成为注册表的主要维护者。添加到你的 `CLAUDE.md` / `AGENT.md`: + +```markdown +## Follow-ups backlog + +- **会话开始**: 浏览 `.devtrail/follow-ups-backlog.md` 以了解项目中所有待处理事项。 +- **Pre-commit 检查**: 创建或修改了任何带有 `## Follow-ups` 或 `R (new, not in Charter)` 条目的 AILOG 吗? → 在同一个 commit 中运行 `scripts/check-followups-drift.sh --apply` 以扩展 backlog。 +- **Charter 关闭后**: 审查 Charter 解决的条目;将其标记为 `closed`(在 `Notes` 中带有关闭 Charter id)或 `superseded`。 +``` + +这使代理成为维护者,脚本成为验证层,操作员成为周期性审查者(重新分类、标记 closed、修剪 superseded)。 + +--- + +## 采用流程 + +对于从零开始的 adopter: + +1. 创建 `.devtrail/follow-ups-backlog.md`,使用上述 frontmatter(初始 `fully_extracted_ailogs:` 列表为空)和五个 `## Bucket: ` 标题。 +2. 将参考脚本从 `StrangeDaysTech/sentinel` 复制到 `scripts/check-followups-drift.sh`。如果你的 AILOG 位于其他位置,调整 `AILOG_DIR`。 +3. 运行 `scripts/check-followups-drift.sh --scan-all --apply` 从现有 AILOG 播种注册表。 +4. 手动将自动生成的 `## Bucket: ready` 条目重新分类到正确的 bucket。这是一次性 triage,对于约 50 个条目的 backlog 通常需要 30-60 分钟。 +5. 将代理集成块添加到 `CLAUDE.md` / `AGENT.md`。 +6. 可选地将 `scripts/check-followups-drift.sh` 接入 pre-commit hook 以进行硬性 enforcement。 + +对于从临时跟踪迁移的 adopter:相同的流程,但步骤 4 可能需要决定哪些条目已经是 `closed` 或 `superseded` — 该分类是使注册表有用的关键。 + +--- + +## 参考实现 + +`StrangeDaysTech/sentinel` CHARTER-12,于 2026-05-06 合并: + +- 实现 PR: [sentinel#53](https://github.com/StrangeDaysTech/sentinel/pull/53)(注册表 + 脚本 + CLAUDE.md 添加)。 +- 关闭 PR: [sentinel#54](https://github.com/StrangeDaysTech/sentinel/pull/54)(合并后验证 + Charter 关闭)。 + +经验上下文: 47 个条目从 CHARTER-08 → CHARTER-11 回顾中播种(约 30 分钟的多代理 triage)。该链条展示了激发该模式的差距 — 没有注册表,操作员无法在不孤立地重新分类每个 Charter 的 follow-ups 的情况下查看"项目中所有待处理事项"。有了注册表,会话开始时的浏览就是一次文件读取。 + +--- + +## 未决问题 + +这些在 v0 中尚未解决。该模式的未来修订版本或 CLI helper 可能会处理它们: + +- **Bucket 分类启发式**。今天 `--apply` 将每个新条目转储到 `## Bucket: ready`;操作员手动重新分类。使用 AILOG `tags` 和 Charter `effort_estimate` 的启发式可以自动建议 bucket。 +- **Schema 验证**。注册表遵循一个隐式 schema;尚不存在 `.devtrail/schemas/follow-ups-backlog.schema.v0.json`。今天的验证是人工审查。 +- **与审计周期的集成**。当 `devtrail charter audit --merge-reports` 产生未在关闭前原子修复的真实 debt findings 时,这些 findings 仅存在于 `.devtrail/audits//review.md` 中。它们不会自动流入中央注册表。自动浮现它们将关闭一个已知差距。 +- **`closed` 与 `superseded` 语义**。今天的差异在于解决工作是否显式引用了该条目。可能会出现更严格的约定。 +- **作为 `devtrail followups` CLI 的结晶化**。一旦第二个 adopter 验证了该模式,framework 可以发布一个子命令,镜像现有的 `devtrail charter` 三件套:`list` / `close` / `drift`。处于 v0 的 adopter(此模式)通过删除其本地脚本并切换代理指令进行迁移。 + +--- + +## 致谢 + +通过 [issue #111](https://github.com/StrangeDaysTech/devtrail/issues/111) 由 Sentinel adopter 贡献。经验基础:`StrangeDaysTech/sentinel` 中的 CHARTER-08 → CHARTER-11 链。作者:Claude Opus 4.7,代表操作员 José Villaseñor Montfort。 + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md index c7a8fa4..4ec92a8 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md @@ -194,4 +194,12 @@ risk_level: low | medium | high | critical --- -*DevTrail v4.9.0 | [Strange Days Tech](https://strangedays.tech)* +## 模式 + +| 模式 | 文档 | +|------|------| +| Follow-ups backlog(中央注册表 + drift 检测) *(fw-4.10.0+)* | [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) | + +--- + +*DevTrail v4.10.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/QUICK-REFERENCE.md b/dist/.devtrail/QUICK-REFERENCE.md index 7877bd7..69c9349 100644 --- a/dist/.devtrail/QUICK-REFERENCE.md +++ b/dist/.devtrail/QUICK-REFERENCE.md @@ -168,4 +168,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.9.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.10.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/dist-manifest.yml b/dist/dist-manifest.yml index e595126..d9f86ac 100644 --- a/dist/dist-manifest.yml +++ b/dist/dist-manifest.yml @@ -1,4 +1,4 @@ -version: "4.9.0" +version: "4.10.0" description: "DevTrail distribution manifest" repository: "https://github.com/StrangeDaysTech/devtrail" diff --git a/docs/adopters/ADOPTION-GUIDE.md b/docs/adopters/ADOPTION-GUIDE.md index fd3ce3f..1be266a 100644 --- a/docs/adopters/ADOPTION-GUIDE.md +++ b/docs/adopters/ADOPTION-GUIDE.md @@ -239,7 +239,7 @@ The CLI automatically: 1. **Download the latest release** - Go to [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) and download the latest `fw-*` release ZIP (e.g., `fw-4.9.0`). + Go to [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) and download the latest `fw-*` release ZIP (e.g., `fw-4.10.0`). 2. **Extract to your project** ```bash diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md index 76a9637..5285822 100644 --- a/docs/adopters/CLI-REFERENCE.md +++ b/docs/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ DevTrail uses **independent version tags** for each component: | Component | Tag prefix | Example | What it includes | |-----------|-----------|---------|------------------| -| Framework | `fw-` | `fw-4.9.0` | Templates (12 types), governance docs, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.10.0` | Templates (12 types), governance docs, directives, Charter template + schema | | CLI | `cli-` | `cli-3.10.0` | The `devtrail` binary | Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa. @@ -88,7 +88,7 @@ Initialize DevTrail in a project directory. ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.9.0 +✔ Downloaded DevTrail fw-4.10.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -110,7 +110,7 @@ If `.devtrail/` does not exist in the current directory, the framework update is ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.9.0 +✔ Framework updated to fw-4.10.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -127,7 +127,7 @@ Update only the framework files. Looks for the latest `fw-*` release on GitHub. ```bash $ devtrail update-framework -✔ Framework updated to fw-4.9.0 +✔ Framework updated to fw-4.10.0 ``` --- @@ -211,7 +211,7 @@ $ devtrail status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.9.0 │ + │ Framework │ fw-4.10.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -268,7 +268,7 @@ Repairing DevTrail in /home/user/my-project → Restoring 1 missing directory... ✓ Restored .devtrail/templates/ → Downloading framework to restore missing files... - Using version: fw-4.9.0 + Using version: fw-4.10.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -1053,7 +1053,7 @@ Show version, authorship, and license information. $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.9.0 + Framework version: fw-4.10.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md index 7402b83..9b3a433 100644 --- a/docs/i18n/es/README.md +++ b/docs/i18n/es/README.md @@ -222,7 +222,7 @@ DevTrail usa tags de versión independientes para cada componente: | Componente | Prefijo de tag | Ejemplo | Incluye | |------------|---------------|---------|---------| -| Framework | `fw-` | `fw-4.9.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | +| Framework | `fw-` | `fw-4.10.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | | CLI | `cli-` | `cli-3.10.0` | El binario `devtrail` | Verifica las versiones instaladas con `devtrail status` o `devtrail about`. @@ -255,7 +255,7 @@ Ver [Referencia CLI](adopters/CLI-REFERENCE.md) para uso detallado. ```bash # Descargar el último release ZIP del framework desde GitHub # Ve a https://github.com/StrangeDaysTech/devtrail/releases -# y descarga el último release fw-* (ej. fw-4.9.0) +# y descarga el último release fw-* (ej. fw-4.10.0) # Extraer y copiar a tu proyecto unzip devtrail-fw-*.zip -d tu-proyecto/ diff --git a/docs/i18n/es/adopters/ADOPTION-GUIDE.md b/docs/i18n/es/adopters/ADOPTION-GUIDE.md index efb1dbf..6e73299 100644 --- a/docs/i18n/es/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/es/adopters/ADOPTION-GUIDE.md @@ -230,7 +230,7 @@ El CLI automáticamente: 1. **Descargar el último release** - Ve a [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) y descarga el último release `fw-*` (ej. `fw-4.9.0`). + Ve a [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases) y descarga el último release `fw-*` (ej. `fw-4.10.0`). 2. **Extraer en tu proyecto** ```bash diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md index 12ea9f5..f1b7e67 100644 --- a/docs/i18n/es/adopters/CLI-REFERENCE.md +++ b/docs/i18n/es/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ DevTrail usa **tags de versión independientes** para cada componente: | Componente | Prefijo de tag | Ejemplo | Qué incluye | |------------|---------------|---------|-------------| -| Framework | `fw-` | `fw-4.9.0` | Plantillas (12 tipos), docs de gobernanza, directivas | +| Framework | `fw-` | `fw-4.10.0` | Plantillas (12 tipos), docs de gobernanza, directivas | | CLI | `cli-` | `cli-3.10.0` | El binario `devtrail` | Framework y CLI se publican de forma independiente. Una actualización del framework no requiere actualización del CLI, y viceversa. @@ -88,7 +88,7 @@ Inicializa DevTrail en un directorio de proyecto. ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.9.0 +✔ Downloaded DevTrail fw-4.10.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -109,7 +109,7 @@ Si `.devtrail/` no existe en el directorio actual, la actualización del framewo ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.9.0 +✔ Framework updated to fw-4.10.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -126,7 +126,7 @@ Actualiza solo los archivos del framework. Busca el último release `fw-*` en Gi ```bash $ devtrail update-framework -✔ Framework updated to fw-4.9.0 +✔ Framework updated to fw-4.10.0 ``` --- @@ -205,7 +205,7 @@ $ devtrail status DevTrail Status ─────────────── Path: /home/user/my-project -Framework version: fw-4.9.0 +Framework version: fw-4.10.0 CLI version: cli-3.5.2 Language: en Structure: ✔ Complete @@ -859,7 +859,7 @@ Muestra información de versión, autoría y licencia. $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.9.0 + Framework version: fw-4.10.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index 3fd76eb..aaf293e 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -240,7 +240,7 @@ DevTrail 为每个组件使用独立的版本标签： | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| -| Framework | `fw-` | `fw-4.9.0` | 模板（12 种类型）、治理文档、指令、Charter 模板 + schema | +| Framework | `fw-` | `fw-4.10.0` | 模板（12 种类型）、治理文档、指令、Charter 模板 + schema | | CLI | `cli-` | `cli-3.10.0` | `devtrail` 二进制文件 | 使用 `devtrail status` 或 `devtrail about` 查看已安装的版本。 @@ -273,7 +273,7 @@ DevTrail 为每个组件使用独立的版本标签： ```bash # 从 GitHub 下载最新的框架发布 ZIP # 前往 https://github.com/StrangeDaysTech/devtrail/releases -# 下载最新的 fw-* 发布（例如 fw-4.9.0） +# 下载最新的 fw-* 发布（例如 fw-4.10.0） # 解压并复制到你的项目 unzip devtrail-fw-*.zip -d your-project/ diff --git a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md index 80786eb..0a145d5 100644 --- a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md @@ -239,7 +239,7 @@ CLI 自动完成： 1. **下载最新版本** - 前往 [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases)，下载最新的 `fw-*` 版本 ZIP（例如 `fw-4.9.0`）。 + 前往 [GitHub Releases](https://github.com/StrangeDaysTech/devtrail/releases)，下载最新的 `fw-*` 版本 ZIP（例如 `fw-4.10.0`）。 2. **解压到你的项目** ```bash diff --git a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md index f310e81..6113e07 100644 --- a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md +++ b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ DevTrail 为每个组件使用**独立的版本标签**： | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| -| Framework | `fw-` | `fw-4.9.0` | 模板（12 种类型）、治理文档、指令 | +| Framework | `fw-` | `fw-4.10.0` | 模板（12 种类型）、治理文档、指令 | | CLI | `cli-` | `cli-3.10.0` | `devtrail` 二进制文件 | Framework 和 CLI 独立发布。Framework 更新不需要 CLI 更新，反之亦然。 @@ -88,7 +88,7 @@ devtrail status # 显示完整的安装状态，包括版本 ```bash $ devtrail init . -✔ Downloaded DevTrail fw-4.9.0 +✔ Downloaded DevTrail fw-4.10.0 ✔ Created .devtrail/ directory structure ✔ Created DEVTRAIL.md ✔ Configured AI agent directives @@ -110,7 +110,7 @@ Next: git add .devtrail/ DEVTRAIL.md && git commit -m "chore: adopt DevTrail" ```bash $ devtrail update Updating framework... -✔ Framework updated to fw-4.9.0 +✔ Framework updated to fw-4.10.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -127,7 +127,7 @@ Updating CLI... ```bash $ devtrail update-framework -✔ Framework updated to fw-4.9.0 +✔ Framework updated to fw-4.10.0 ``` --- @@ -211,7 +211,7 @@ $ devtrail status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.9.0 │ + │ Framework │ fw-4.10.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -268,7 +268,7 @@ Repairing DevTrail in /home/user/my-project → Restoring 1 missing directory... ✓ Restored .devtrail/templates/ → Downloading framework to restore missing files... - Using version: fw-4.9.0 + Using version: fw-4.10.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -993,7 +993,7 @@ $ devtrail explore --lang es # 会话内切换到西班牙语 $ devtrail about DevTrail CLI CLI version: cli-3.5.2 - Framework version: fw-4.9.0 + Framework version: fw-4.10.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/devtrail