maxgfr/construct

construct — una idea de producto, fundamentada en un SRD construible

construct convierte una idea de producto en un conjunto de Documentos de Requisitos de Software (SRD) cuyos requisitos y decisiones están fundamentados en investigación real, no en la memoria del modelo. El motor determinista (scripts/construct.mjs, Node sin dependencias) realiza la búsqueda, el ensamblaje del dossier, el renderizado del SRD y la validación con código; tu trabajo es realizar la entrevista, dirigir la investigación y enriquecer el andamio renderizado hasta obtener un SRD preciso y bien fundamentado.

La regla principal: prefiere un requisito fundamentado a uno supuesto. Utiliza la investigación que el motor recupera (competidores, proyectos OSS similares, documentación técnica, StackOverflow) para justificar el alcance, los requisitos no funcionales (NFR) y las decisiones arquitectónicas, y cita la evidencia con [E#]. La fundamentación es consultiva aquí — construct check informa la cobertura pero nunca falla por ello — así que el rigor depende de ti.

El script

Un paquete único, sin dependencias: node scripts/construct.mjs <comando>. No requiere npm install, ni claves API. Ejecuta --help para ver todas las opciones. Comandos clave:

• init --idea "<idea en una línea>" --out <ejecución> — crea la carpeta de ejecución + brief.json.
• research --out <ejecución> [--angles market,oss,tech,semantic] [--q "<enfoque>"] [--semantic] — recopila evidencia en diferentes ángulos dentro de <ejecución>/evidence/ (un dossier EVIDENCE.md + evidence.json con identificadores [E#]). Ángulos predeterminados: market,oss,tech.
• analyze --out <ejecución> [--json] — el informe "qué falta": nombra cada característica/competidor/tecnología/semilla que se renderizará SIN FUNDAMENTAR, y muestra el comando de profundización que corrige cada vacío. Informativo, nunca bloquea.
• web|oss|tech|so --out <ejecución> [--q "<enfoque>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — profundiza en UN ángulo (salida estándar, sin dossier). Úsalo para indagar más en un hilo débil; --docs-url fundamenta páginas de documentación conocidas directamente.
• render --out <ejecución> [--level light|complex] [--merge] — renderiza el árbol SRD + SRD.json a partir de brief.json y el dossier.
• check --out <ejecución> [--min-grounding <0-100>] [--semantic] [--json] — la validación ESTRUCTURAL (código de salida ≠ 0 si el SRD está incompleto) más el informe CONSULTIVO de cobertura de fundamentación. --min-grounding N activa una segunda compuerta que falla si hay menos del N% de afirmaciones fundamentadas; --semantic incluye VERIFY.json (ver review) y falla si hay afirmaciones refutadas o sin soporte. (Distinto de research --semantic, que solo reordena la evidencia según relevancia de embeddings).
• review --out <ejecución> [--apply <verdictos.json>] [--max-review N] [--json] — el sistema de soporte de afirmaciones. Sin --apply escribe una lista de trabajo afirmación↔evidencia (VERIFY.todo.json + VERIFY.md): cada afirmación fundamentada emparejada con cada fragmento [E#] citado para su adjudicación. --apply <verdictos.json> reduce tus veredictos (supported|partial|refuted|unsupported) en VERIFY.json, que check --semantic valida. Divídelo según references/orchestration.md.
• verify --out <ejecución> [--app <dir>] [--run-tests] [--strict] [--json] — el árbitro de construcción: BUILD-PLAN.json bien formado y acíclico, cada referencia de tarea resuelta en SRD.json, archivos de tareas completadas existentes, cada requisito referenciado por una prueba. --run-tests también ejecuta los comandos de prueba declarados; --strict falla si una característica obligatoria construida no tiene ninguna prueba que la referencie.
• status --out <ejecución> [--json] — qué existe en la ejecución hasta ahora; --json añade la frontera de construcción (qué tareas de BUILD-PLAN se pueden construir ahora vs. están bloqueadas).
• semantic up|down|status — pila Docker local opcional (Qdrant + Ollama + SearXNG).

Flujo de trabajo

Se te invoca una vez y se espera que devuelvas un SRD completo y fundamentado. Conduce el bucle hasta completarlo; solo haz una pausa para preguntar al usuario una decisión real.

1. Entrevista al usuario — una pregunta a la vez. Establece el producto antes de investigar. Sigue references/interview-playbook.md: problema, usuarios objetivo, valor principal, características obligatorias/deberían/podrían, restricciones (presupuesto, cronograma, equipo, cumplimiento normativo), tecnologías candidatas y cualquier semilla de competidor / OSS. Recomienda una respuesta con cada pregunta; no sueltes un cuestionario. Escribe las respuestas en brief.json (inícialo con construct init).

2. Investiga — fundamenta la idea. Ejecuta:

   node scripts/construct.mjs research --out <ejecución> --angles market,oss,tech
   

   Esto descubre competidores en la web, extrae proyectos OSS comparables (y sus issues/PRs para problemas reales) y obtiene documentación de tecnologías candidatas + StackOverflow. Lee <ejecución>/evidence/EVIDENCE.md.

3. Profundiza — hasta que analyze esté limpio o el usuario te detenga. Ejecuta:

   node scripts/construct.mjs analyze --out <ejecución>
   

   Identifica exactamente qué es débil — características, competidores, tecnologías candidatas y semillas OSS sin evidencia coincidente — y muestra el comando de profundización que corrige cada vacío. Distribuye: si puedes lanzar subagentes en paralelo, envía uno por cada vacío; cada uno recibe la idea en una línea, el vacío, su comando de profundización y su propia BúsquedaWeb, y devuelve un resumen de ≤5 líneas más URLs valiosas para fundamentar. Los subagentes NO DEBEN escribir en la carpeta de ejecución — las profundizaciones imprimen en salida estándar; solo construct research escribe el dossier, y solo TÚ lo ejecutas. Incorpora los hallazgos en serie: construct web --url <u,...> --out <ejecución> → volver a ejecutar research → volver a ejecutar analyze. (¿No tienes subagentes? Trabaja los vacíos tú mismo, una profundización a la vez.) Informa al usuario lo que encontraste y déjale dirigir — prioriza las características obligatorias y las decisiones críticas, detente cuando él diga que es suficiente. Consulta references/orchestration.md y references/research-playbook.md.

4. Renderiza el SRD. Cuando el brief sea sólido y el dossier esté completo:

   node scripts/construct.mjs render --out <ejecución> --level complex
   

   Elige complex siempre que sea posible construir algo; cambiar de nivel más tarde renumerará los IDs de FR (consulta references/srd-authoring.md). Esto escribe el árbol SRD (ver más abajo). El modelo de datos y las interfaces vienen preinicializados por inferencia del brief — verifícalos, no confíes en ellos. Luego enriquécelo: resuelve cada nota 🧠 Decide:, afina los criterios de aceptación plantillados y las métricas NFR en declaraciones comprobables y acotadas (sigue references/acceptance-criteria.md — check advierte mientras queden plantillados), corrige/amplía el modelo de datos y las interfaces, y añade citas [E#] del dossier a los requisitos y decisiones que las sustentan. Consulta references/srd-authoring.md y references/citation-format.md. En nivel complex, enriquece también el sistema de diseño (design/): reemplaza los tokens de diseño inicializados con los valores reales de la marca del producto, verifica el inventario de componentes y pantallas/flujos, y afina los criterios de accesibilidad según el estándar objetivo (derivado del brief, por defecto WCAG 2.2 AA). Consulta references/design-system-authoring.md.

5. Revisión adversarial — deja que ojos nuevos lo rompan. Lanza un subagente revisor SIN contexto más allá de la ruta de la carpeta de ejecución y references/adversarial-review.md (¿no tienes subagentes? haz la revisión tú mismo, siguiendo estrictamente esa lista de verificación como un lector hostil). Debe intentar romper el SRD — ambigüedad, criterios no comprobables, rutas de fallo faltantes, blanqueo de citas, contradicciones — y devolver hallazgos etiquetados. Corrige cada [blocker], usa tu criterio con [advisory], luego vuelve a ejecutar check. Repite mientras aparezcan nuevos bloqueadores (límite: 3 rondas, luego presenta lo que quede al usuario). Para una ADR genuinamente controvertida y difícil de revertir en nivel complex, ejecuta también el panel de 3 jueces de references/orchestration.md.

6. Valida (tres capas).

   • Estructural (rígida): node scripts/construct.mjs check --out <ejecución>. Falla si hay 🧠 sin resolver, ningún requisito funcional, un FR sin criterios de aceptación, una referencia a entidad/interfaz/NFR colgante, una categoría NFR requerida faltante o una ADR mal formada. Corrige hasta que pase.
   • Fundamentación (consultiva): el mismo comando imprime la cobertura — qué fracción de requisitos/decisiones citan evidencia. Auméntala donde importe (las decisiones críticas); consulta references/grounding-coverage.md. Por defecto nunca hace fallar la construcción, así que usa tu criterio. Cuando el usuario quiera que la fundamentación sea obligatoria, añade la compuerta opcional: check --out <ejecución> --min-grounding 70.
   • Soporte de afirmaciones (consultiva → compuerta opcional): la cobertura cuenta citas; no verifica que sean válidas. construct review --out <ejecución> construye una lista de trabajo afirmación↔evidencia; adjudica cada par (distribuye según references/orchestration.md Patrón 4), ensambla verdictos.json, review --apply verdictos.json, luego check --out <ejecución> --semantic para bloquear afirmaciones refutadas o sin soporte. Vale la pena una pasada sobre los FR/ADRs críticos antes de presentar. Repite los pasos 3–6 hasta que check pase estructuralmente, el revisor no encuentre nuevos bloqueadores y la fundamentación sea honesta.

7. Presenta. Entrega al usuario el conjunto SRD: la visión, el panorama competitivo, los requisitos fundamentados y las decisiones clave (con su evidencia [E#] y enlaces). Señala explícitamente cualquier incógnita en lugar de adivinar.

8. Construye (cuando el usuario quiera la aplicación, no solo el SRD). El renderizado también emitió BUILD-PLAN.json — un DAG de tareas legible por máquina (esqueleto T-000 + una tarea por FR, obligatorio → debería → podría, dependencias conscientes de entidades) cuyas entradas acceptance APUNTAN a SRD.json. Tú escribes todo el código de la aplicación; el motor actúa como árbitro. Sigue references/build-playbook.md:

   • Haz T-000 (andamio, soporte de pruebas, CI); establece conventions.appDir y conventions.testCommand en BUILD-PLAN.json.
   • Por tarea, en orden topológico: lee los criterios de aceptación de SRD.json; aplícalos con TDD — cada prueba nombra su ID de FR (ej. describe("FR-001 …"); eso es lo que verify busca); registra artifacts + tests; establece status: "done"; ejecuta node scripts/construct.mjs verify --out <ejecución> y corrige cualquier error antes de la siguiente tarea.
   • Las tareas del mismo hito no tienen aristas entre sí, por lo que su frontera lista (status --out <ejecución> --json) se puede construir en paralelo — un árbol de trabajo git aislado por tarea; tú solo integras los resultados en BUILD-PLAN.json (Patrón 5 en references/orchestration.md).
   • Por hito: verify --out <ejecución> --run-tests --strict, luego una revisión adversarial del hito — ojos nuevos buscando un criterio de aceptación que ninguna prueba ejercite realmente (consulta el playbook; references/verify.md explica qué puede y qué no puede demostrar verify).
   • Si un FR resulta incorrecto durante la construcción, modifica el brief, vuelve a renderizar (el progreso se fusiona por título de característica), reetiqueta los IDs de FR desplazados, vuelve a ejecutar check.

Lo que produce (el árbol SRD, en --out)

00-overview/   VISION.md · SCOPE.md (+ decisiones abiertas 🧠)
requirements/  FUNCTIONAL.md (FR-NNN · prioridad · Dado/Cuando/Entonces · [E#])
               NON-FUNCTIONAL.md (NFR-NNN por categoría · métrica · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADRs)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (solo complex; --no-design para omitir)
competitive/   LANDSCAPE.md (competidores + proyectos OSS similares)
BUILD-PLAN.md · BUILD-PLAN.json (DAG de tareas para la fase de construcción)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ entidad ↔ interfaz ↔ componente ↔ pantalla)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light lo mantiene ligero; complex añade el conjunto completo de NFR, una segunda ADR, criterios de aceptación de rutas de fallo, la matriz de trazabilidad completa y un subárbol de sistema de diseño (design/: principios, tokens, componentes, pantallas/flujos, un contrato de accesibilidad — --no-design lo omite). Añade --merge para un único archivo SRD.md.

Modo semántico opcional (totalmente local, sin clave API)

Los ángulos market/OSS/tech solo necesitan acceso a la red. Para una pasada de relevancia sobre la evidencia recopilada, puedes habilitar un modelo de embeddings local:

node scripts/construct.mjs semantic up        # docker: Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <ejecución> --angles market,oss,tech,semantic --semantic

Todo se ejecuta en contenedores Docker locales — sin clave, ningún dato sale de la máquina. Si la pila no está activa, --semantic registra un aviso y mantiene la clasificación léxica. Consulta references/semantic-setup.md.

Referencias

• references/interview-playbook.md — cómo obtener el brief, una pregunta a la vez.
• references/research-playbook.md — cómo elegir ángulos y profundizar hasta que sea "suficientemente bueno".
• references/orchestration.md — el modelo de flujo de trabajo dinámico de tres niveles y los patrones de subagentes: distribución de investigación, equipo rojo, panel de jueces, distribución de revisión de soporte de afirmaciones, distribución de construcción (y la regla de un solo escritor).
• references/adversarial-review.md — la lista de verificación del equipo rojo y su contrato de hallazgos.
• references/srd-authoring.md — cómo resolver las notas 🧠, escribir requisitos y ADRs comprobables.
• references/design-system-authoring.md — cómo enriquecer el sistema de diseño complex: tokens, componentes, pantallas/flujos y el contrato de accesibilidad.
• references/acceptance-criteria.md — reescrituras de Dado/Cuando/Entonces de malo a bueno y patrones de métricas NFR medibles.
• references/citation-format.md — la convención de fundamentación [E#].
• references/grounding-coverage.md — qué significa el informe consultivo de cobertura y cómo mejorarlo.
• references/build-playbook.md — el bucle de construcción: TDD de tareas, convención de etiquetas FR, compuertas de hito, la revisión de hito.
• references/verify.md — qué demuestra cada verificación de verify y qué aún necesita ojos humanos.
• references/provider-apis.md — cómo se obtienen issues/PRs de OSS por host, sin clave.
• references/web-discovery.md — la búsqueda web en capas sin clave.
• references/semantic-setup.md — la pila Docker local opcional.