dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: dod_evidence_schema templates + READMEs (issue 0114)

Browse Source 
- docs/templates/issue.md and docs/templates/flow.md include the optional
  dod_evidence_schema: block with realistic example items.
- dev/issues/README.md and dev/flows/README.md document the schema, kinds
  by example, validation rules and the fn doctor dod entrypoint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Egutierrez
2026-05-18 18:13:02 +02:00
parent c5587842b9
commit 581d0f0a0e
4 changed files with 235 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev/flows/README.md
+42
View File
@@ -56,6 +56,48 @@ Regla: si la respuesta a "donde lo ves" es "en una BD" o "en un log" -> NO vale.
`/flow done` rechaza el cierre si falta alguno de los 4 user-facing checks o si `## Notas` no contiene parrafo onboarding.
### DoD evidence schema (issue 0114, opcional)
Ademas de los checkboxes humanos del bloque `## Definition of Done`, cada flow puede declarar en su frontmatter un bloque `dod_evidence_schema:` con la version maquinable de la DoD: lista de evidencias con id unico, `kind` cerrado, `expected` libre y `required` bool. Auditable con `fn doctor dod`.
```yaml
dod_evidence_schema:
- id: surface_dashboard
kind: url
expected: "https://metabase.organic-machine.com/dashboard/12 muestra ultimo refresh hoy"
required: true
- id: matrix_room_msg
kind: screenshot
expected: "sala matrix #flows recibe mensaje con resumen del run"
required: true
- id: data_factory_run
kind: cmd
expected: "sqlite3 data_factory.db 'SELECT count(*) FROM runs WHERE flow=NNNN' > 0"
required: true
- id: error_path_log
kind: log
expected: "fallar collector intencional deja entry status=error sin crash"
required: false
```
Reglas:
- `kind` ∈ {`screenshot`, `log`, `url`, `cmd`}.
- `id` unico por flow.
- `expected` no vacio.
- `required` default `true`.
Ejemplos por kind:
| kind | que pones en `expected` |
|---|---|
| `screenshot` | "frame de la app/sala mostrando estado Y" |
| `log` | "fichero <path> contiene linea con texto Z" |
| `url` | "GET <url> devuelve 200 con campo W" o "dashboard tal carga ultima fila < 24h" |
| `cmd` | comando shell con exit 0 (incluido SQL via sqlite3) |
Plantilla canonica: `docs/templates/flow.md`. Validador: `fn doctor dod` + `audit_dod_schema_go_infra`.
## Para agentes / LLMs
Antes de crear o editar un flow, lee `AGENT_GUIDE.md`. Define:
dev/issues/README.md
+42
View File
@@ -2,6 +2,48 @@
> **Frontmatter YAML** es la fuente de verdad desde 2026-05-17 (issue 0100).
> Cada `.md` empieza con bloque `---` con `id`, `title`, `status`, `type`, `domain`, `scope`, `priority`, `depends`, `blocks`, `related`, `created`, `updated`, `tags`.
## DoD evidence schema (issue 0114, opcional)
Cualquier issue puede declarar en su frontmatter un bloque `dod_evidence_schema:` que enumera **evidencias concretas** capturables al cerrar. Es la version maquinable del bloque humano `## Definition of Done`: lista de items con id unico, `kind` cerrado, `expected` libre y `required` bool. Auditable con `fn doctor dod` (sale humana y `--json`).
```yaml
dod_evidence_schema:
- id: surface_1_board_drag
kind: screenshot
expected: "kanban_cpp board con card en columna Doing (agent)"
required: true
- id: backend_health
kind: cmd
expected: "curl -fsS http://localhost:8403/api/health == 200"
required: true
- id: timeline_entry
kind: url
expected: "http://localhost:8486/api/runs?app=kanban_cpp devuelve >=1 run"
required: false
- id: agent_log
kind: log
expected: "agent_runs/<run_id>/agent.log contiene 'workflow done'"
required: true
```
Reglas:
- `kind` ∈ {`screenshot`, `log`, `url`, `cmd`}. Otro valor rechaza el item.
- `id` unico por issue (los duplicados se reportan).
- `expected` no vacio (descripcion observable de la evidencia).
- `required` bool (default `true` si se omite).
Ejemplos por kind:
| kind | que pones en `expected` |
|---|---|
| `screenshot` | "frame de la UI X mostrando estado Y" — capturable manual o por test visual |
| `log` | "fichero <path> contiene linea con texto Z" — grep-eable |
| `url` | "GET <url> devuelve 200 y body con campo W" — curl-eable |
| `cmd` | comando que debe terminar con exit 0 (o assert explicito) |
Plantilla canonica: `docs/templates/issue.md`. Validador: `fn doctor dod` + `audit_dod_schema_go_infra`.
> Para listar/filtrar: `/issue list --domain trading --status pendiente` (cuando `dev_console` exista — issue 0101).
>
> Dominios canonicos: `meta cpp-stack kanban trading gamedev osint data-ingest registry-quality notify imagegen apps-infra dev-ux deploy frontend mcp browser telemetry docs`.