Cambio (Brownfield)

¿Qué hace Cambio (Brownfield)?

Agrega un cambio acotado y revisable a una especificación y código base existentes sin redactar un nuevo PRD. Un cambio produce una propuesta más exactamente un paquete de tareas de cuatro documentos; después de que QA lo apruebe, los deltas confirmados se escriben de vuelta en la especificación y la propuesta se archiva. Este skill es primero por instrucciones (prompt-first): cada paso tiene un plan de contingencia manual y los scripts incluidos son ayudantes opcionales.

Posición en el pipeline: spec-generator -> cambio -> task-decomposition -> plan-linter (Compuerta 1) -> revisión (Compuerta 2) -> dev -> qa -> convergencia -> archivo.

especificación existente + cambio acotado
  -> .specs/change-context/standards.md        (standards_extract.py; restricciones implícitas)
  -> .specs/changes/<id-cambio>/proposal.md    (ciclo de vida: propuesta -> aplicada -> archivada)
  -> tasks/<id-cambio>/01..04                  (un contrato, un paquete)
  -> Compuerta 1 plan-linter -> Compuerta 2 revisión -> dev <-> qa -> convergencia -> propuesta archivada

Cuándo usarlo

• Una especificación existente o una base de código ya publicada necesita un cambio incremental: corrección de errores, una funcionalidad pequeña, un ajuste de comportamiento, un ajuste acotado de NFR.
• El cambio puede reutilizar un anclaje #sec-* existente y se ajusta al presupuesto de diferencias micro/estándar.
• Deseas el ciclo propuesta -> aplicar -> archivar manteniendo el protocolo de tareas de cuatro documentos de este repositorio y los roles de un propietario por archivo.

Cuándo NO usarlo

• El trabajo es desde cero o no existe aún una especificación previa: usa prd-generator, luego spec-generator y luego task-decomposition.
• El cambio necesita una nueva decisión de arquitectura, un nuevo límite de componente, una nueva invariante transversal o una sección de especificación completamente nueva (un nuevo anclaje #sec-*): escala a spec-generator en lugar de colarlo como un cambio.
• Solo necesitas dividir una especificación aprobada en tareas: usa task-decomposition.
• Solo necesitas auditar paquetes o propuestas existentes: usa plan-linter.
• La tarea ya está planificada y esperando implementación/verificación: usa dev / qa.

Entradas

• La especificación base: .specs/02-tech-spec.md (y sus partes modulares) por defecto.
• El requisito para el cambio acotado, escrito por el solicitante en lenguaje sencillo.
• El informe de convenciones del repositorio generado en el paso 1.
• Opcional: el paquete de tareas existente del que el cambio continúa y las ADR relevantes.

Salidas

Artefacto	Propietario después del andamiaje	Propósito
.specs/change-context/standards.md	Herramientas	Estándares deterministas del repositorio y restricciones implícitas (generado, nunca editado a mano).
.specs/changes/<id-cambio>/proposal.md	Planificador	Propuesta de cambio acotado: motivación, diff incremental, alcance del impacto, invariantes/NFR, reversión, verificación.
.specs/changes/<id-cambio>/convergence.md	Herramientas de convergencia	Escrito después de que QA apruebe; registra lo que se reincorporó a la especificación.
tasks/<id-cambio>/01-contract.md ... 04-process.md	Planificador / Dev / QA / herramientas	Exactamente un paquete de cuatro documentos, reutilizando las plantillas de descomposición de tareas.

La propuesta no es un PRD y no es una especificación de reemplazo. Es un delta que nombra los anclajes existentes que modifica. Ciclo de vida completo y reglas de tamaño: references/brownfield-protocol.md.

Flujo de trabajo

1. Extraer estándares del repositorio (una vez por cambio de configuración):

   python .agents/skills/change/scripts/standards_extract.py --repo-root . --json
   python .agents/skills/change/scripts/standards_extract.py --repo-root . --check
   

   Lee .specs/change-context/standards.md antes de planificar. Su sección "Restricciones implícitas" es vinculante: usa solo los comandos que evidencia, respeta la estructura de pruebas declarada, los requisitos mínimos de ejecución y los anclajes existentes. El código de salida 1 de --check significa que el informe está desactualizado; regenérelo antes de planificar. Nunca edites el informe a mano.

2. Andamiar la propuesta y un paquete de tareas (el único paso que escribe archivos):

   python .agents/skills/change/scripts/scaffold_change.py \
     --change-id CHG-001-rate-limit \
     --title "Límite de velocidad en intentos de inicio de sesión" \
     --anchor "#sec-auth-tokens" \
     --kind modify \
     --size-class micro --estimated-lines 40 \
     --touch-files "modify:src/auth/rate_limit.py" \
     --repo-root .
   

   El andamiador valida los anclajes contra la especificación base, calcula base_spec_sha256 y delega en task-decomposition (scaffold_task.py) o emite un paquete mínimo en línea si está ausente. Usa --dry-run para previsualizar y --force para sobrescribir ejecuciones desechables.

3. El planificador completa la propuesta y el contrato. Reemplaza las guías en la propuesta (motivación, fragmentos [CHG-<n>], rutas, invariantes/NFR, reversión, verificación) y los marcadores de posición del contrato (module, adherence_adrs, dod, casos límite, texto de invariante). No inventes rutas ni anclajes. Mantén los formularios de rol 02/03 en blanco; mantén la propuesta status: proposed.

4. Compuerta 1, luego Compuerta 2. Ejecuta la Compuerta 1 determinista, luego la revisión semántica independiente:

   # Ejecutar desde la raíz del repositorio. El ayudante de la Compuerta 1 requiere que el skill plan-linter esté instalado.
   python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes
   python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-rate-limit --repo-root .
   

   La Compuerta 1 debe pasar antes de la implementación; la Compuerta 2 no debe informar BLOQUEADO o SOLICITAR CAMBIOS.

5. Implementar y verificar. Ejecuta dev (solo los touch_files declarados, completa 02, entrega) y qa (pruebas independientes bajo tests/acceptance/, completa 03, un veredicto). La propuesta pasa a applied una vez que la implementación y la verificación sean exitosas.

6. Converger y archivar. Después de QA_PASSED, ejecuta converge para agregar las desviaciones confirmadas a .specs/02-tech-spec.md, escribe convergence.md, mueve el paquete a tasks/archive/ y establece el estado de la propuesta status: archived. Sin converge, realiza la escritura de agregado idéntico manualmente.

Plan de contingencia manual (sin Python)

1. Construye la lista de estándares a mano: configuraciones de la raíz del repositorio, árboles de prueba/código fuente, runtime, anclajes #sec-*.
2. Copia assets/templates/proposal.template.md a .specs/changes/<id-cambio>/proposal.md, completa cada marcador ({{...}}) y calcula base_spec_sha256.
3. Crea el paquete de cuatro documentos tasks/<id-cambio>/ usando las plantillas de task-decomposition o el plan de contingencia en references/brownfield-protocol.md.
4. Ejecuta las listas de verificación de la Compuerta 1 / Compuerta 2 manualmente; registra la evidencia en el paquete.
5. Sigue los pasos del flujo de trabajo 5–6 con los mismos artefactos.

Lista de verificación de compuerta de calidad

• Informe de estándares generado y actualizado (standards_extract.py --check sale con 0).
• Metadatos de la propuesta completos, status: proposed, kind correcto, base_spec_sha256 actualizado.
• Cada bloque [CHG-<n>] nombra un anclaje #sec-* real que existe en la especificación base.
• Existe exactamente un paquete de tareas; change_id es igual al id de la propuesta y origin_spec_anchor es uno de los impact_anchors de la propuesta.
• Presupuesto de diferencias respetado: micro es 1 archivo de modificación (por defecto 10-49 líneas); estándar es 1-3 archivos (por defecto 50-250 líneas). Números configurables en la configuración de plan-linter.
• La Compuerta 1 pasa en el contrato completo y la propuesta está abierta (proposed/applied).
• La revisión de la Compuerta 2 no tiene hallazgos bloqueantes; el revisor es independiente y de solo lectura.
• Dev implementó solo los touch_files; QA emitió exactamente un veredicto con evidencia.
• Convergencia agregó los deltas a la especificación y la propuesta está archived.

Reglas contra la alucinación

• Nunca inventes rutas de archivos. Cada entrada touch_files debe ser un archivo existente para modify o un archivo nuevo en un directorio existente para create (relativo al repositorio, con barras diagonales).
• Cada fragmento de diff nombra un anclaje real. Reutiliza un anclaje #sec-* existente; el andamiador y el linter rechazan anclajes faltantes o desviados.
• No inventes comandos ni convenciones. Solo los comandos evidenciados por la configuración declarada (el informe de estándares) pueden aparecer en la Definición de Hecho (DoD) del contrato.
• Un cambio estructural escala. Si el cambio necesita una nueva sección/anclaje de especificación, un nuevo componente, una nueva ADR o un cambio de invariante, detente y usa spec-generator.
• No exageres las compuertas. La Compuerta 1 es contabilidad determinista, la Compuerta 2 es una revisión basada en instrucciones; git y CI siguen siendo autoritativos.

Scripts auxiliares

• scripts/standards_extract.py — extractor determinista de estándares; escribe .specs/change-context/standards.md (--json, --check, --dry-run, --version).
• scripts/scaffold_change.py — crea la propuesta y un paquete de tareas (--dry-run, --force, --json, --version).
• scripts/lint_change.py — verificación de coherencia propuesta/paquete y desviación de la especificación base (--json, --version).

Todos los ayudantes usan solo la biblioteca estándar de Python, resuelven su propio directorio y salen con 0 (éxito), 1 (fallo de compuerta), 2 (error de uso), 3 (error inesperado).

Manejo de fallos

• Especificación base faltante: Detente. Un cambio brownfield requiere una especificación base; el andamiador sale con 2.
• Anclaje desconocido: Detente y reutiliza un anclaje existente, o escala a spec-generator.
• Informe desactualizado o desviación de especificación (salida 1): Regenera el informe, rebasa la propuesta, vuelve a ejecutar la Compuerta 1; nunca edites a mano base_spec_sha256.
• El directorio de cambio ya existe: Vuelve a ejecutar con --force solo si es desechable; de lo contrario, edita la propuesta existente.
• Scripts no disponibles: Sigue el plan de contingencia manual; el flujo de trabajo es primero por instrucciones.

Límites honestos

• El informe de estándares describe la configuración declarada, no necesariamente la práctica aplicada; es una instrucción para el Planificador, no una prueba de cumplimiento.
• base_spec_sha256 detecta cualquier cambio de byte en la especificación base; después de la convergencia, la propuesta archivada está exenta de comprobaciones de desviación.
• Los scripts opcionales se pueden omitir; CI más los permisos del repositorio siguen siendo autoritativos.