Documentos corporativos

Un acta o un informe en STXT es a la vez el documento que leen las personas y los datos que procesa un programa.

Un acta de reunión

Minutes (com.acme.corp.minutes):
	Title: Sincronización semanal de Plataforma
	Date: 2026-01-09
	Attendees:
		Attendee: Joan Costa
		Attendee: Mery Adams
		Attendee: Keyla Brown

	Notes >>
		El roadmap del trimestre va según lo previsto, pero falta cerrar la
		capacidad del equipo para febrero.

		Se acuerda mover la ventana de despliegue del viernes al lunes, para tener
		soporte completo el día siguiente.

	Decisions:
		Decision: Mover la ventana de despliegue al lunes
			Id: DEC-0142
			Decision status: Approved
			Owner: Platform Team
			Rationale >>
				El soporte del martes es completo y el del sábado no.
		Decision: Congelar cambios no críticos en el módulo X
			Id: DEC-0143
			Decision status: Proposed
			Owner: Reliability

	Actions:
		Action: Preparar la propuesta de capacidad del trimestre
			Id: ACT-0991
			Owner: Mery Adams
			Due: 2026-01-16
			Action status: Open
		Action: Estimar el coste de la opción B
			Id: ACT-0992
			Owner: Joan Costa
			Due: 2026-01-14
			Action status: In Progress

En este ejemplo hay dos tipos de contenido:

Datos: los asistentes, las decisiones y las acciones. Son nodos inline, uno por elemento.
Texto: las notas de la reunión y el motivo de una decisión. Son nodos block, y se escriben sin ninguna restricción.

El criterio es práctico: es dato lo que alguien va a buscar, filtrar o contar. Por ejemplo, un programa puede obtener las acciones del acta sin interpretar nada:

Action	Id	Owner	Due	Action status
`Preparar la propuesta de capacidad del trimestre`	ACT-0991	Mery Adams	2026-01-16	Open
`Estimar el coste de la opción B`	ACT-0992	Joan Costa	2026-01-14	In Progress

La plantilla

Una plantilla define qué debe tener un acta, qué es opcional y qué estados existen:

Template (@stxt.template): com.acme.corp.minutes
	Structure >>
		Minutes:
			Title: (1)
			Date: (1) DATE
			Attendees: (1)
				Attendee: (+)
			Notes: (?) TEXT
			Decisions: (?)
				Decision: (*)
					Id: (1)
					Decision status: (1) ENUM [Proposed, Approved, Rejected]
					Owner: (?)
					Rationale: (?) TEXT
			Actions: (?)
				Action: (*)
					Id: (1) @Id
					Owner: (?) @Owner
					Due: (?) DATE
					Action status: (1) ENUM [Open, In Progress, Done, Blocked]

Dentro de un namespace, un nombre identifica un solo nodo. Por eso Id y Owner se definen una vez y se reutilizan con @Id y @Owner. Y por eso hay un Decision status y un Action status: tienen valores distintos, así que son nodos distintos.

Un acta que no valida

# ERROR: este documento no valida
Minutes (com.acme.corp.minutes):
	Title: Sincronización semanal de Plataforma
	# El día 32 no existe
	Date: 2026-01-32
	# `Atendees` no está en la plantilla (le falta una `t`), y falta `Attendees`
	Atendees:
		Attendee: Joan Costa
	Actions:
		Action: Preparar la propuesta de capacidad del trimestre
			Id: ACT-0991
			# `Pendiente` no es un estado de la lista
			Action status: Pendiente

La plantilla es la lista completa de lo que puede aparecer: un nodo que no está en ella se rechaza (modelo de contenido cerrado).

Un informe de estado

Lo mismo sirve para cualquier documento periódico:

Status Report (com.acme.corp.status):
	Project: Portal de clientes
	Owner: Platform Docs
	Period:
		From: 2026-01-05
		To: 2026-01-09
	Status: Green

	Summary >>
		Avance sostenido en la documentación base. Queda trabajo en la
		referencia de la línea de comandos, que no bloquea la entrega de febrero.

	Progress:
		Item: Página de introducción
			Item status: Done
		Item: Tutorial
			Item status: Done
		Item: Referencia de la línea de comandos
			Item status: In Progress

	Risks:
		Risk: Faltan ejemplos de migración desde otros formatos
			Id: RSK-020
			Level: Medium
			Mitigation >>
				Preparar dos ejemplos de migración antes del cierre del trimestre.

Y su plantilla:

Template (@stxt.template): com.acme.corp.status
	Structure >>
		Status Report:
			Project: (1)
			Owner: (1)
			Period: (1)
				From: (1) DATE
				To: (1) DATE
			Status: (1) ENUM [Green, Amber, Red]
			Summary: (1) TEXT
			Progress: (?)
				Item: (*)
					Item status: (1) ENUM [Done, In Progress, Blocked]
			Risks: (?)
				Risk: (*)
					Id: (1)
					Level: (1) ENUM [Low, Medium, High]
					Mitigation: (?) TEXT

El semáforo Status es un ENUM. Con veinte informes en un directorio, un programa puede responder cuántos proyectos están en Red y cuáles son sus riesgos High.

Cómo se trabaja

Los documentos viven en un repositorio, con la plantilla en el directorio .stxt/.
Un cambio es un diff de líneas: una acción que pasa de Open a Done, una decisión nueva.
La extensión de VS Code autocompleta nombres y estados, y marca los errores al escribir.
stxt validate --recursive minutes/ hace la misma validación en integración continua.

Todo esto se explica en El entorno de trabajo.

Límites

La plantilla no valida reglas entre campos (por ejemplo, que una acción Done no tenga una fecha futura). Esa lógica es de la aplicación que usa los datos.

STXT tampoco aporta flujo de aprobación, control de acceso ni notificaciones.