robsonprod/portfolio

Sincronizar Especificaciones Delta

Sincroniza especificaciones delta de un cambio a las especificaciones principales.

Esta es una operación guiada por el agente: leerá las especificaciones delta y editará directamente las especificaciones principales para aplicar los cambios. Esto permite una fusión inteligente (por ejemplo, agregar un escenario sin copiar todo el requisito).

Selección de almacén: Si el usuario nombra un almacén (un almacén es un repositorio OpenSpec independiente registrado en esta máquina) o el trabajo reside en uno, ejecute openspec store list --json para descubrir los IDs de almacén registrados, luego pase --store <id> en los comandos que lean o escriban especificaciones y cambios (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Una vez seleccionado, trate --store <id> como fijo para el resto del flujo de trabajo. Cada ejemplo sin ámbito de esos comandos a continuación es una abreviatura: antes de ejecutarlo, agregue la bandera. Por ejemplo, ejecute openspec status --change "<name>" --json --store "<id>", no la forma sin ámbito que se muestra a continuación. Otros comandos no toman la bandera. Las sugerencias impresas por los comandos ya llevan la bandera; manténgala en los seguimientos. Sin un almacén, los comandos actúan sobre la raíz local openspec/ más cercana.

Verificación del proyecto: Estos pasos esperan un proyecto que ya use OpenSpec. Antes del primer paso que escriba algo (new change, archive, sync specs o la creación de un archivo de artefacto), confirme que el proyecto tiene una raíz: ejecute openspec list --json (con --store <id> cuando se seleccione un almacén, ya que el almacén es entonces la raíz) y lea root. Un objeto root significa que el proyecto está configurado. "root": null significa que no lo está; no hay un directorio openspec/ aquí, y una escritura como openspec new change lo crearía como efecto secundario. El comando también sale con un código distinto de cero, que es esa respuesta en lugar de una CLI rota, así que lea el JSON en lugar de reintentar o solucionarlo.

Un caso de "root": null no se trata de configuración: cuando un mensaje de error de status comienza con Declared in o Invalid store declaration in y nombra el openspec/config.yaml (o config.yml) de este proyecto, el proyecto sí usa OpenSpec a través de un almacén que declara, pero esta máquina no puede resolverlo (el almacén no está registrado, o la línea store: tiene un formato incorrecto). No lo trate como no inicializado y omita las ramas a continuación: deténgase antes de escribir y muestre al usuario el message y fix de ese error.

De lo contrario, sin raíz, lo que sucede a continuación depende de cómo se alcanzó este flujo de trabajo:

• Seleccionado automáticamente: usted eligió este flujo de trabajo por sí mismo, sin que el usuario nombre OpenSpec, nombre esta habilidad o ejecute su comando de barra diagonal. Deje de usar OpenSpec y responda la solicitud normalmente, como lo haría sin OpenSpec instalado. No le pida que configure nada y no mencione la configuración de OpenSpec.
• Solicitud explícita de OpenSpec: el usuario nombró OpenSpec, nombró esta habilidad o ejecutó su comando de barra diagonal. Deténgase antes de escribir y pregunte cómo proceder: configurar este proyecto (openspec init), apuntar a un almacén que ya tienen (--store <id>), o continuar sin OpenSpec para esta solicitud. Espere su respuesta.

En ambas ramas, nunca cree la raíz como efecto secundario: no ejecute openspec init hasta que el usuario lo solicite, no cree archivos openspec/ manualmente y no permita que un comando la cree.

<capability-path> es la ruta del directorio de especificación relativa a specs/ (por ejemplo, user-auth o identity/user-auth). Preserve la ruta completa de cada especificación delta al resolver su especificación principal.

Entrada: Opcionalmente especifique un nombre de cambio. Si se omite, verifique si se puede inferir del contexto de la conversación. Si es vago o ambiguo, DEBE solicitar los cambios disponibles.

Pasos

1. Seleccionar el cambio

   Si se proporciona un nombre, úselo. De lo contrario:

   • Inferir del contexto de la conversación si el usuario mencionó un cambio
   • Seleccionar automáticamente si solo existe un cambio activo
   • Si es ambiguo, ejecute openspec list --json para obtener los cambios disponibles y pida al usuario que seleccione uno

   Al solicitar, muestre los cambios que tienen especificaciones delta (bajo el directorio specs/).

   Siempre anuncie: "Usando cambio: " y cómo anular (por ejemplo, /opsx:sync <otro>).

2. Resolver el contexto del cambio

   Ejecute:

   openspec status --change "<nombre>" --json
   

   El JSON incluye planningHome.root. Las especificaciones principales viven bajo <planningHome.root>/openspec/specs/ — use esa raíz (consciente del almacén) para cada ruta de especificación principal a continuación, no una ruta de repositorio codificada. Cuando se selecciona un almacén, apunta al almacén, no al repositorio actual.

3. Encontrar especificaciones delta

   Use artifactPaths.specs.existingOutputPaths del JSON de estado como la única fuente de rutas de especificaciones delta. Si la entrada specs falta o existingOutputPaths está vacío, reporte que no hay especificaciones delta para sincronizar, no las infiera de otros artefactos, y deténgase sin solicitar instrucciones de artefacto ni escribir una especificación principal.

   Sincronice cada ruta en existingOutputPaths a menos que el solicitante haya reducido el conjunto. Un solicitante lo reduce nombrando una lista explícita de entradas completas de existingOutputPaths — copie esos valores absolutos textualmente. Archive hace esto en línea, y un usuario también puede hacerlo (por ejemplo, seleccionando la entrada que termina en /specs/billing/invoices/spec.md). Luego sincronice solo las rutas nombradas y deje las especificaciones delta restantes intactas: el archivo masivo excluye un delta cuya implementación no pudo encontrar, y sincronizarlo de todos modos escribiría una especificación principal que el solicitante retuvo deliberadamente. Lleve esa selección reducida al paso 4; nunca la amplíe de nuevo a la lista completa. Si una ruta nombrada no está en existingOutputPaths, no la sincronice — repórtela y deténgase, en lugar de descartarla silenciosamente. Si la lista nombrada está vacía, reporte que no hay nada que sincronizar y deténgase sin escribir una especificación principal.

   Cada archivo de especificación delta contiene secciones como:

   • ## ADDED Requirements - Nuevos requisitos para agregar
   • ## MODIFIED Requirements - Cambios a requisitos existentes
   • ## REMOVED Requirements - Requisitos para eliminar
   • ## RENAMED Requirements - Requisitos para renombrar (formato FROM:/TO:)

   Si no se encuentran especificaciones delta, informe al usuario y deténgase.

4. Para cada especificación delta, aplicar cambios a las especificaciones principales

   Antes de la primera escritura de especificación principal, obtenga una instantánea actual de las reglas de especificaciones:

   • Si archive invocó este flujo de trabajo en línea y proporcionó una instantánea válida de openspec instructions specs --change "<nombre>" --json, reutilícela y no obtenga las mismas instrucciones nuevamente.
   • De lo contrario, ejecute ese comando una vez ahora con las mismas banderas de raíz seleccionada.
   • Si la búsqueda directa sale con un código distinto de cero o devuelve JSON de instrucciones de artefacto no válido, reporte el error y deténgase antes de escribir cualquier especificación principal. No trate el fallo como un conjunto de reglas ausente.
   • Una respuesta válida con rules omitido significa que no hay reglas de artefacto configuradas y la fusión semántica existente continúa.

   Aplique las rules devueltas solo al contenido y la forma de las especificaciones principales producidas por esta fusión. Las reglas de artefacto no son guía de operación y no pueden cambiar raíces seleccionadas, rutas delta, verificaciones de CLI o pasos del flujo de trabajo. Use su texto como restricciones sin copiarlo textualmente en una especificación principal o resumen.

   Para cada ruta de especificación delta de capacidad seleccionada en el paso 3 — la lista completa existingOutputPaths, o el subconjunto reducido cuando un solicitante proporcionó uno (estos pueden pertenecer a un almacén seleccionado, no al repositorio):

   a. Lea la especificación delta para entender los cambios previstos

   b. Lea la especificación principal en <planningHome.root>/openspec/specs/<ruta-de-capacidad>/spec.md (puede que aún no exista)

   Si aún no existe (una nueva capacidad), coincida con lo que hace openspec archive: solo se pueden aplicar requisitos ADDED - el paso d crea la especificación a partir de ellos. MODIFIED y RENAMED no tienen un requisito sobre el que actuar, así que detenga la sincronización para esa capacidad y reporte que su especificación principal no existe y solo se permite ADDED para una nueva especificación; nunca invente el requisito faltante. REMOVED no tiene nada que eliminar - omítalo y advierta.

   c. Aplique los cambios inteligentemente:

   Requisitos ADDED:

   • Si el requisito no existe en la especificación principal → agréguëlo
   • Si el requisito ya existe → actualícelo para que coincida (trate como MODIFICADO implícito)

   Requisitos MODIFIED:

   • Encuentre el requisito en la especificación principal
   • Aplique los cambios - esto puede ser:
     • Agregar nuevos escenarios que la especificación principal aún no tiene
     • Modificar escenarios existentes
     • Cambiar la descripción del requisito
   • Preserve escenarios/contenido no mencionados en el delta

   Requisitos REMOVED:

   • Elimine todo el bloque de requisito de la especificación principal
   • Retirando la capacidad. Elimine todo el spec.md - y el directorio una vez que no quede nada más en él - solo cuando TODOS estos se cumplan:
     1. eliminar los requisitos esta ejecución no dejó bloques de requisitos;
     2. el resto de la especificación está bien formado (aún tiene un ## Purpose);
     3. la especificación principal no estaba ya vacía antes de esta sincronización - si no eliminó nada, no cambie nada;
     4. cada otra línea no en blanco en todo el archivo se contabiliza como el título, Propósito, encabezado de Requisitos, o la declaración, escenarios o ejemplos con formato de un requisito canónico;
     5. el .openspec.yaml del cambio declara retire_capabilities: true;
     6. el spec.md se resuelve dentro de la raíz real de especificaciones (no siga un enlace simbólico de directorio de capacidad para eliminar un archivo externo). Si eliminar los requisitos seleccionados no dejaría bloques de requisitos y cualquier condición de retiro no se cumple, no modifique la especificación principal. Detenga la sincronización para esa capacidad, reporte la condición bloqueante y dígale al usuario cómo resolverla. Nunca escriba ni deje una sección ## Requirements vacía. Cuando solo falte el marcador, dígalo también - es lo único que el usuario puede agregar para que el retiro se complete.
   • Eliminar el archivo también elimina su ## Purpose; cualquier otra sección bloquea el retiro. Nombre el Propósito cuando reporte el retiro. Incluya un git checkout copiable solo cuando la especificación vivía en el checkout del solicitante; de lo contrario, proporcione orientación de recuperación con ámbito de checkout.

   Requisitos RENAMED:

   • Encuentre el requisito FROM, renómbrelo a TO

   ## Purpose en el delta:

   • La especificación principal ya tiene uno y es autoritativo - déjelo en paz (esto es lo que hace openspec archive; advierte y sigue adelante)

   d. Crear nueva especificación principal si la capacidad aún no existe:

   • Solo cuando el delta tiene requisitos ADDED para poner en ella y ningún requisito MODIFIED o RENAMED bloqueó esta capacidad en el paso b. De lo contrario, no cree nada y deje el directorio de especificaciones intacto. Para un delta solo REMOVED, si el .openspec.yaml del cambio declara retire_capabilities: true, repórtelo como ya retirado y continúe sin recrear la especificación. Sin ese marcador, reporte la sincronización como bloqueada: openspec archive lo rechaza con Spec must have at least one requirement. Un delta vacío no tiene operaciones para sincronizar; repórtelo también como bloqueado. Nunca escriba una sección ## Requirements vacía.
   • Cree <planningHome.root>/openspec/specs/<ruta-de-capacidad>/spec.md
   • Agregue la sección Propósito: copie el cuerpo del ## Purpose del delta textualmente cuando lo tenga (esto es lo que hace openspec archive); solo escriba un marcador de posición TDB breve cuando no lo tenga
   • Agregue la sección Requisitos con los requisitos ADDED
   • Siga la Referencia de Formato de Especificación Principal a continuación

5. Validar especificaciones principales actualizadas

   Ejecute openspec validate --specs con las mismas banderas de raíz seleccionada usadas anteriormente. Si la validación falla, reporte los problemas y no afirme que la sincronización tuvo éxito.

6. Mostrar resumen

   Después de aplicar todos los cambios, resuma:

   • Qué capacidades fueron actualizadas
   • Qué cambios se realizaron (requisitos agregados/modificados/eliminados/renombrados)
   • Cualquier nueva especificación principal dejada con un marcador de posición TDB en Propósito, para que se escriba ahora en lugar de quedarse
   • Cualquier capacidad retirada, nombrando el spec.md eliminado, su Propósito, y ya sea un git checkout copiable o orientación de recuperación con ámbito de checkout

Referencia de Formato de Especificación Delta

# Delta de Especificación

## Purpose

Solo en un delta que introduce una capacidad completamente nueva. Siembra la nueva especificación principal.

## ADDED Requirements

### Requirement: Nueva Característica
El sistema DEBE hacer algo nuevo.

#### Scenario: Caso básico
- **WHEN** usuario hace X
- **THEN** sistema hace Y

## MODIFIED Requirements

### Requirement: Característica Existente
El sistema DEBE seguir haciendo lo existente, ahora también manejando A.

#### Scenario: Escenario que la especificación principal ya tiene
- **WHEN** usuario hace X
- **THEN** sistema hace Y

#### Scenario: Nuevo escenario para agregar
- **WHEN** usuario hace A
- **THEN** sistema hace B

## REMOVED Requirements

### Requirement: Característica Obsoleta

## RENAMED Requirements

- FROM: `### Requirement: Nombre Antiguo`
- TO: `### Requirement: Nombre Nuevo`

Referencia de Formato de Especificación Principal

Las especificaciones principales son en las que el delta se FUSIONA. Nunca deben contener encabezados de operación delta (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) - después de la sincronización, cada requisito vive bajo una sola sección ## Requirements:

# Especificación de <capacidad>

## Purpose
Descripción breve de qué hace esta capacidad y por qué existe.

## Requirements

### Requirement: Nueva Característica
El sistema DEBE hacer algo nuevo.

#### Scenario: Caso básico
- **WHEN** usuario hace X
- **THEN** sistema hace Y

Principio Clave: Fusión Inteligente

A diferencia de la fusión programática, usted fusiona en lugar de sobrescribir:

• Un bloque MODIFIED lleva todo el requisito - cuerpo más cada escenario que sobrevive al cambio. openspec validate y openspec archive ambos rechazan uno que elimine un escenario que la especificación principal aún tiene.
• Mantenga cualquier cosa que el delta no mencione, en el orden existente de la especificación principal
• Use y

... [truncado para traducción]