feat(papers): estructura, scaffolding y capability page del artefacto papers/

Nuevo tipo de artefacto para papers académicos reproducibles (papers/<NNNN-slug>/):

- Plantillas docs/templates/paper.md (IMRaD completo con guías por sección:
  Abstract, Introduction, Related work, Methods, Results, Discussion con
  Limitaciones + Amenazas a la validez, Conclusion + Future work) y
  docs/templates/preregistration.md (H0/H1 falsable, variables, diseño, plan
  de análisis con test exacto + effect size + corrección múltiple, predicción
  cuantitativa; nota anti-HARKing de congelado).
- Pipeline init_paper (bash/functions/pipelines/init_paper.sh + .md): calcula el
  siguiente NNNN, crea las subcarpetas (experiments data figures reviews out),
  copia las plantillas rellenando el frontmatter (title, slug, date, phase=question,
  status=draft) y crea references.md. No hace git init (fase interna local).
- Función atómica reutilizable next_numbered_dir (bash/functions/io): siguiente
  prefijo NNNN- escaneando un directorio numerado (reutilizable por papers/reports/issues).
- papers/ como artefacto local gitignored (bloque en .gitignore + papers/.gitkeep):
  un paper en fase interna no contamina el repo padre; al promocionar a publishable
  se vuelve sub-repo Gitea propio.
- Página de capacidad docs/capabilities/papers.md + fila en el INDEX: tabla de
  funciones del grupo papers (disponibles + en construcción por la flota), ejemplo
  canónico end-to-end y fronteras.

Reutiliza slugify_ascii del registry. Diseño: reports/0001-2026-06-30-papers-system-design.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-30 20:38:38 +02:00
parent a1e2e3567c
commit 6e3c3cf2a2
10 changed files with 593 additions and 0 deletions
+58
View File
@@ -0,0 +1,58 @@
---
name: next_numbered_dir
kind: function
lang: bash
domain: io
version: "1.0.0"
purity: impure
signature: "next_numbered_dir(parent_dir: string, [width: int]) -> string"
description: "Calcula el siguiente prefijo numerico NNNN- para un directorio numerado incremental. Escanea los subdirectorios directos de parent_dir cuyo nombre empiece por NNNN- (4+ digitos seguidos de guion), toma el maximo, le suma 1 y lo imprime con zero-padding al ancho width (default 4). Si parent_dir no existe o no tiene subdirs que matcheen, imprime 0001."
tags: [papers, io, scaffold]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
- name: parent_dir
desc: "directorio padre cuyos subdirectorios numerados (NNNN-...) se escanean; obligatorio"
- name: width
desc: "ancho del zero-padding del numero impreso (default 4); opcional"
output: "el siguiente numero como string con zero-padding a width digitos a stdout (ej. 0003); usage a stderr y exit 1 si falta parent_dir"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/io/next_numbered_dir.sh"
---
## Ejemplo
```bash
source bash/functions/io/next_numbered_dir.sh
# Sobre un papers/ que ya contiene 0001-foo y 0002-bar
mkdir -p /tmp/papers/{0001-foo,0002-bar}
next_numbered_dir /tmp/papers
# -> 0003
# Directorio vacio o inexistente -> primer numero
next_numbered_dir /tmp/papers_nuevo
# -> 0001
# Ancho de padding distinto
next_numbered_dir /tmp/papers 6
# -> 000003
```
## Cuando usarla
Cuando scaffoldees un artefacto numerado incremental (papers/, reports/, issues/) y necesites el siguiente NNNN sin colision: escanea lo que ya existe en disco y te da el numero libre listo para crear `<NNNN>-<slug>`.
## Gotchas
- **Impura**: lee el filesystem (estado del directorio en el momento de la llamada). No crea nada — solo calcula e imprime el numero.
- **Octal**: los numeros con cero a la izquierda (`08`, `09`) se interpretan como octal en aritmetica bash y romperian el calculo. La funcion fuerza base 10 con `10#$num` para evitarlo.
- **Solo subdirectorios**: cuenta unicamente subdirs directos. Archivos sueltos (`.gitkeep`, `notas.md`) y subdirs que no matcheen el patron se ignoran. No es recursivo.
- **Patron estricto**: el prefijo debe ser `NNNN-` (minimo 4 digitos seguidos de guion). Un subdir `12-foo` o `0001foo` (sin guion) NO se cuenta.
- No hay deteccion de huecos: devuelve `max+1`, no el primer numero libre intermedio. Si tienes `0001` y `0003`, devuelve `0004`, no `0002`.
+46
View File
@@ -0,0 +1,46 @@
#!/usr/bin/env bash
# next_numbered_dir — Compute the next NNNN- prefix for a numbered directory.
#
# Scans the DIRECT subdirectories of <parent_dir> whose names start with a
# numeric prefix of the form `NNNN-` (4+ digits followed by a hyphen), takes
# the maximum number, adds 1, and prints it zero-padded to <width> (default 4).
# If <parent_dir> does not exist or contains no matching subdir, prints the
# first number (0001 at default width).
next_numbered_dir() {
local parent_dir="${1:-}"
local width="${2:-4}"
if [[ -z "$parent_dir" ]]; then
echo "usage: next_numbered_dir <parent_dir> [width]" >&2
return 1
fi
local max=0
local entry base num
if [[ -d "$parent_dir" ]]; then
# Iterate only over direct subdirectories. The trailing slash in the
# glob ensures files (e.g. .gitkeep) are skipped — only dirs match.
for entry in "$parent_dir"/*/; do
# If the glob matched nothing it stays literal; guard with -d.
[[ -d "$entry" ]] || continue
base="$(basename "$entry")"
# Require a prefix of 4+ digits followed by a hyphen.
if [[ "$base" =~ ^([0-9]{4,})- ]]; then
num="${BASH_REMATCH[1]}"
# Force base 10 so leading zeros (08, 09) are not read as octal.
num=$((10#$num))
if (( num > max )); then
max=$num
fi
fi
done
fi
printf "%0*d\n" "$width" $(( max + 1 ))
}
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
next_numbered_dir "$@"
fi