You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The textual + authoring half of Loom's Architecture Plan view (Spec 002) — the operator's "where are we?" answered from the terminal, ahead of the visual overlay (A2). All surfaces are **EXPERIMENTAL (Loom v0)** and may change without a deprecation cycle.
| CLI |`cli-`|`cli-3.24.0`| The `straymark` binary |
51
+
| CLI |`cli-`|`cli-3.25.0`| The `straymark` binary |
52
52
| Loom (EXPERIMENTAL) |`loom-`|`loom-0.4.2`| The `straymark-loom` visualization server, downloaded on demand by `straymark loom serve`|
53
53
54
54
Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa.
@@ -239,6 +239,45 @@ $ straymark status
239
239
→ Run straymark explore to browse documentation interactively
240
240
```
241
241
242
+
#### `straymark status --where [path] [--out <dir>]`*(cli-3.25.0+, EXPERIMENTAL)*
243
+
244
+
The textual **"you are here"** companion to Loom's Architecture Plan view (the terminal half of the dashboard). Loads `architecture/model.yml` and projects each component's state from your live governance signals, so you can answer *"where are we?"* without opening a browser.
245
+
246
+
> ⚠️ **EXPERIMENTAL (Loom v0).** Requires an `architecture/model.yml` (see `straymark architecture generate`). The output shape may change without a deprecation cycle.
247
+
248
+
| Flag | Default | Description |
249
+
|---|---|---|
250
+
|`--where`| off | Switch `status` into the architecture projection view |
251
+
|`--out <dir>`|`.straymark/architecture`| Directory holding `model.yml` (point it elsewhere to project a model kept outside `.straymark/`) |
252
+
253
+
Each component is tagged with one or more states, derived purely from governance (no new frontmatter):
254
+
255
+
-**`active`** — an `in-progress` Charter declares files matching the component (← *you are here*);
256
+
-**`in-progress`** — within an active component, declared files already touched (declared ∩ git-modified);
257
+
-**`implemented`** — a closed Charter (and its AILOGs) touched the component;
258
+
-**`has-debt`** — an open `TDE` relates to the component;
259
+
-**`uncharted`** — files on disk that no Charter or document references.
260
+
261
+
The view ends with a **"Where are we" summary**: the active Charter, declared-vs-modified progress, recent AILOGs, and open debt. The `active`/`implemented` flags line up with `straymark charter list --status in-progress`/`--status closed` + `charter drift` by construction (one shared projection).
262
+
263
+
```
264
+
$ straymark status --where
265
+
266
+
Where are we
267
+
268
+
Tooling (Rust workspace)
269
+
▸ straymark-cli [active] [in-progress] ← you are here
Author and maintain the **architecture model** that powers Loom's Architecture Plan view (Spec 002): a semantic `model.yml` (components → file globs + layers + links) paired with a `plan.drawio` blueprint, linked by a stable `component_id` (the BIM "model vs drawing" split). The textual projection over this model is `straymark status --where`; the visual overlay is Loom (A2).
1428
+
1429
+
> ⚠️ **EXPERIMENTAL (Loom v0).** The model schema, DrawIO conventions, and command surface may change without a deprecation cycle. All three subcommands operate on `.straymark/architecture/` by default; `--out <dir>` overrides it.
1430
+
1431
+
**`straymark architecture generate [path] [--force] [--out <dir>]`** — write a first-draft `model.yml` + `plan.drawio` by mining your codebase structure (one component per top-level source directory, glob `dir/**`) enriched with ADR signal (C4 Mermaid diagrams + "Affected Components" tables improve labels and add links). Components land in a placeholder `unassigned` layer and the `.straymark` stages 00–09 seed the layer list — you then refine by hand (reassign/rename layers, tighten globs, add links). `--force` overwrites existing artifacts.
1432
+
1433
+
**`straymark architecture sync [path] [--out <dir>] [--apply]`** — **append-only** reconciliation: detect new top-level source directories / ADR components not yet covered by the model and append them to `model.yml` + `plan.drawio`, **never** clobbering human edits or DrawIO geometry. Dry-run by default; `--apply` writes.
1434
+
1435
+
**`straymark architecture validate [path] [--out <dir>] [--output <text|json|markdown>]`** — report model↔plan integrity signals: **undrawn** (component with no DrawIO cell), **unmodeled** (a DrawIO cell absent from the model), **empty** (globs match no files on disk). **Exits 1** when any signal is found (CI-gateable). Degrades to glob-coverage-only when `plan.drawio` is absent.
1436
+
1437
+
| Subcommand | Key flags | Writes? |
1438
+
|---|---|---|
1439
+
|`generate`|`--force`, `--out`| Yes (refuses to overwrite without `--force`) |
1440
+
|`sync`|`--apply`, `--out`| Only with `--apply` (append-only) |
1441
+
|`validate`|`--output`, `--out`| No (read-only; exit 1 on any signal) |
1442
+
1443
+
**Example:**
1444
+
1445
+
```bash
1446
+
$ straymark architecture generate
1447
+
✓ Wrote .straymark/architecture/model.yml (4 components, 9 layers)
1448
+
✓ Wrote .straymark/architecture/plan.drawio
1449
+
→ Mined 3 ADRs: 2 labels improved, 1 link added.
1450
+
→ Refine by hand: reassign components from `unassigned` to real layers, then open the plan in DrawIO.
1451
+
1452
+
$ straymark architecture validate
1453
+
✓ Architecture model is consistent (4 components).
Launch **Loom**, the EXPERIMENTAL knowledge-graph visualization server: a loopback-only, read-only web dashboard that renders the project's StrayMark documents as a live force-directed graph (nodes colored by Louvain community and sized by connectivity; node and corpus-stat panels; server-side metadata/date filters; selecting a node lights up its whole thread of relationships; edits to watched `.md` files update the open browser in under a second).
| CLI |`cli-`|`cli-3.24.0`| El binario `straymark`|
51
+
| CLI |`cli-`|`cli-3.25.0`| El binario `straymark`|
52
52
| Loom (EXPERIMENTAL) |`loom-`|`loom-0.4.2`| El servidor de visualización `straymark-loom`, descargado bajo demanda por `straymark loom serve`|
53
53
54
54
Framework y CLI se publican de forma independiente. Una actualización del framework no requiere actualización del CLI, y viceversa.
@@ -224,6 +224,47 @@ Documents:
224
224
225
225
---
226
226
227
+
#### `straymark status --where [path] [--out <dir>]`*(cli-3.25.0+, EXPERIMENTAL)*
228
+
229
+
El acompañante textual del **"estás aquí"** de la vista del Plan de Arquitectura de Loom (la mitad en terminal del dashboard). Carga `architecture/model.yml` y proyecta el estado de cada componente a partir de tus señales de gobernanza en vivo, de modo que puedas responder *"¿dónde estamos?"* sin abrir un navegador.
230
+
231
+
> ⚠️ **EXPERIMENTAL (Loom v0).** Requiere un `architecture/model.yml` (ver `straymark architecture generate`). La forma de la salida puede cambiar sin ciclo de deprecación.
232
+
233
+
| Flag | Default | Descripción |
234
+
|---|---|---|
235
+
|`--where`| off | Cambia `status` a la vista de proyección de arquitectura |
236
+
|`--out <dir>`|`.straymark/architecture`| Directorio que contiene `model.yml` (apúntalo a otro sitio para proyectar un modelo mantenido fuera de `.straymark/`) |
237
+
238
+
Cada componente se etiqueta con uno o más estados, derivados puramente de la gobernanza (sin nuevo frontmatter):
239
+
240
+
-**`active`** — un Charter `in-progress` declara archivos que coinciden con el componente (← *estás aquí*);
241
+
-**`in-progress`** — dentro de un componente activo, archivos declarados ya tocados (declarados ∩ modificados-en-git);
242
+
-**`implemented`** — un Charter cerrado (y sus AILOGs) tocó el componente;
243
+
-**`has-debt`** — un `TDE` abierto se relaciona con el componente;
244
+
-**`uncharted`** — archivos en disco que ningún Charter o documento referencia.
245
+
246
+
La vista termina con un **resumen "Where are we"**: el Charter activo, el progreso declarados-vs-modificados, los AILOGs recientes y la deuda abierta. Los flags `active`/`implemented` se alinean con `straymark charter list --status in-progress`/`--status closed` + `charter drift` por construcción (una sola proyección compartida).
247
+
248
+
```
249
+
$ straymark status --where
250
+
251
+
Where are we
252
+
253
+
Tooling (Rust workspace)
254
+
▸ straymark-cli [active] [in-progress] ← you are here
255
+
· straymark-core [implemented]
256
+
257
+
Visualization
258
+
· Loom [has-debt]
259
+
260
+
Summary
261
+
Active Charter: A1.4 — status --where
262
+
Progress: 1/2 declared files touched (50%)
263
+
Debt: 1 component with open debt, 0 uncharted
264
+
```
265
+
266
+
---
267
+
227
268
### `straymark repair [path]`
228
269
229
270
Repara una instalación de StrayMark rota restaurando directorios y archivos del framework faltantes.
Crea y mantén el **modelo de arquitectura** que alimenta la vista del Plan de Arquitectura de Loom (Spec 002): un `model.yml` semántico (componentes → globs de archivos + capas + enlaces) emparejado con un plano `plan.drawio`, vinculados por un `component_id` estable (la separación BIM "modelo vs dibujo"). La proyección textual sobre este modelo es `straymark status --where`; la superposición visual es Loom (A2).
1120
+
1121
+
> ⚠️ **EXPERIMENTAL (Loom v0).** El esquema del modelo, las convenciones de DrawIO y la superficie de comandos pueden cambiar sin ciclo de deprecación. Los tres subcomandos operan sobre `.straymark/architecture/` por defecto; `--out <dir>` lo sobrescribe.
1122
+
1123
+
**`straymark architecture generate [path] [--force] [--out <dir>]`** — escribe un primer borrador de `model.yml` + `plan.drawio` minando la estructura de tu base de código (un componente por directorio de fuentes de nivel superior, glob `dir/**`) enriquecido con señal de ADRs (los diagramas C4 Mermaid + las tablas "Affected Components" mejoran las etiquetas y añaden enlaces). Los componentes aterrizan en una capa `unassigned` de relleno y las etapas 00–09 de `.straymark` siembran la lista de capas — luego refinas a mano (reasignar/renombrar capas, ajustar globs, añadir enlaces). `--force` sobrescribe los artefactos existentes.
1124
+
1125
+
**`straymark architecture sync [path] [--out <dir>] [--apply]`** — reconciliación **append-only** (solo-añadir): detecta nuevos directorios de fuentes de nivel superior / componentes de ADRs todavía no cubiertos por el modelo y los añade a `model.yml` + `plan.drawio`, sin **nunca** pisar las ediciones humanas ni la geometría de DrawIO. Dry-run por defecto; `--apply` escribe.
1126
+
1127
+
**`straymark architecture validate [path] [--out <dir>] [--output <text|json|markdown>]`** — reporta señales de integridad modelo↔plan: **undrawn** (componente sin celda de DrawIO), **unmodeled** (una celda de DrawIO ausente del modelo), **empty** (globs que no coinciden con ningún archivo en disco). **Sale con 1** cuando se encuentra cualquier señal (gestionable en CI). Degrada a solo-cobertura-de-globs cuando `plan.drawio` está ausente.
1128
+
1129
+
| Subcomando | Flags clave | ¿Escribe? |
1130
+
|---|---|---|
1131
+
|`generate`|`--force`, `--out`| Sí (rehúsa sobrescribir sin `--force`) |
1132
+
|`sync`|`--apply`, `--out`| Solo con `--apply` (append-only) |
1133
+
|`validate`|`--output`, `--out`| No (solo-lectura; sale con 1 ante cualquier señal) |
1134
+
1135
+
**Ejemplo:**
1136
+
1137
+
```bash
1138
+
$ straymark architecture generate
1139
+
✓ Wrote .straymark/architecture/model.yml (4 components, 9 layers)
1140
+
✓ Wrote .straymark/architecture/plan.drawio
1141
+
→ Mined 3 ADRs: 2 labels improved, 1 link added.
1142
+
→ Refine by hand: reassign components from `unassigned` to real layers, then open the plan in DrawIO.
1143
+
1144
+
$ straymark architecture validate
1145
+
✓ Architecture model is consistent (4 components).
Lanza **Loom**, el servidor EXPERIMENTAL de visualización del grafo de conocimiento: un dashboard web solo-loopback y solo-lectura que renderiza los documentos StrayMark del proyecto como un grafo de fuerzas en vivo (nodos coloreados por tipo de documento, dimensionados por conectividad; seleccionar un nodo ilumina todo su hilo de relaciones; las ediciones a archivos `.md` vigilados actualizan el navegador abierto en menos de un segundo).
0 commit comments