Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

archive and sync skills merge every `specs/**/*.md` as a delta spec, including files `validate` rejects

Abierto Apto para principiantes
  • ¿Algo no está bien?
#2,173 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@clay-good ya está trabajando en esto.

Desde el 29/10/2026.

  • #2174 de @clay-good — abierto

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
78/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript
Área
developer-experience, tooling

Línea de trabajo

Read the archive-change.ts step 4 and sync-specs.ts step 3 instructions, then compare their use of artifactPaths.specs.existingOutputPaths with the <capability-path>/spec.md rule and discoverSpecFiles. Check the generated skill templates on main and run the archive and sync workflows with a stray specs/user-auth/notes.md file. Done when both workflows stop before writing main specs and explain how to move those requirements into spec.md; verify the valid spec.md path still syncs.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

bug needs-triage
What you were trying to do

Archive a change with /opsx:archive, or sync it with /opsx:sync, when a delta was written to a second file beside a capability's spec.md, for example specs/user-auth/notes.md.

What happened

#1869 fixed the CLI side of this. instructions apply now warns ("specs/user-auth/notes.md is not a capability's spec.md, so openspec validate rejects it and archive never merges it"), and openspec archive validates and refuses the change.

The agent workflows still take their delta set from artifactPaths.specs.existingOutputPaths. That list resolves the schema glob specs/**/*.md, so it includes notes.md:

  • archive-change.ts step 4: "Use artifactPaths.specs.existingOutputPaths … as the only delta-spec source".
  • sync-specs.ts step 3: "Sync every path in existingOutputPaths".

Neither workflow runs openspec validate, and neither checks the <capability-path>/spec.md shape. The agent therefore merges notes.md's requirements into openspec/specs/user-auth/spec.md and moves the change to the archive, which is exactly what the CLI now refuses to do. The skills and the CLI disagree about which files are deltas.

Open PR #1796 delegates the final move to openspec archive --skip-specs. CLI validation would then refuse at the end, but only after the skill's inline sync has already written the stray requirements into the main specs. So that PR does not close this.

What you expected instead

The archive and sync skills treat only specs/<capability-path>/spec.md as delta specs, the same set discoverSpecFiles reads. For any other file under specs/, they stop before writing a main spec and tell the user to move its requirements into the capability's spec.md, as the apply warning says. Running openspec validate <name> before the sync would cover this and any future validate/skill drift.

Minimal steps to reproduce
openspec init --tools claude
openspec new change add-logout
# write proposal.md, design.md, tasks.md
mkdir -p openspec/changes/add-logout/specs/user-auth
# specs/user-auth/spec.md   -> "## ADDED Requirements / ### Requirement: Password Login" + scenario
# specs/user-auth/notes.md  -> "## ADDED Requirements / ### Requirement: Logout" + scenario
openspec status --change add-logout --json | jq '.artifactPaths.specs.existingOutputPaths'
# [".../specs/user-auth/notes.md", ".../specs/user-auth/spec.md"]
openspec validate add-logout   # exit 1

Then run /opsx:archive add-logout. Step 4 reads both paths as delta specs and offers "Sync now". The sync merges Logout into the main spec, and step 5 moves the change.

OpenSpec version

Reproduced on 1.14.3. The templates are unchanged on main @ 6d04a1b (1.15.0). Related: #1869 (CLI side, closed), #2163 (archive reads only artifactPaths.specs, open), #1796 (open PR).

Coding agent and model

Claude Code, Claude Opus. Found by reading the generated skills against status/validate output; the gap is in the instruction text.

Agent session trace

No response

OS and Node version

macOS, Node 24

Lenguaje dominante
TypeScript
Estrellas
73k
Forks
5k
Merge medio
2 d 12 h
PR fusionados (30 d)
54

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Fission-AI/OpenSpec

Todos los issues de Fission-AI/OpenSpec

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.