[Proposal/Enhancement] Hardcoded spec format prevents custom schemas from working

[lsmonki]

Problem

OpenSpec hardcodes spec structure expectations (## Requirements, ### Requirement:, #### Scenario: inline) throughout parsers, validators, and generators. This means custom schemas that define different formats (e.g., ## Functional Requirements, scenarios in separate verify.md files) fail validation even when their specs are correctly structured according to their own schema.

This prevents OpenSpec from working with projects that have pre-existing specs in different formats. Real-world scenarios include:

• Teams with specs created before adopting OpenSpec
• Specs generated by other tools
• Human-written specs following company/team conventions
• Custom schemas that use different headers (e.g., ## Functional Requirements) or separate verification files

OpenSpec should adapt to existing spec formats, not impose its own.

Root cause

The spec format is embedded in code, not read from the schema. The schema defines the workflow (artifacts), but OpenSpec ignores it when parsing and validating specs.

Expected behavior

Schemas should be able to define their spec structure via artifact configuration. OpenSpec should read this configuration and adapt its parsing, validation, and generation accordingly.

Proposal

Configurable Spec Format

Why

OpenSpec currently hardcodes spec structure expectations throughout the codebase:

• ## Requirements as the requirements section header
• ### Requirement: {name} as the requirement header pattern
• #### Scenario: {name} as inline scenario headers
• Scenarios expected inline within spec.md

What Changes

• schema.yaml: Extend schema with validation config (changeValidation, specValidation) and artifact fields for spec structure
• Parsers: Make markdown-parser.ts and requirement-blocks.ts configurable based on schema
• Validators: Pass spec format configuration to validation logic
• Generators: Use schema's spec format when generating new specs and deltas
• Sync/Archive: Respect configured format when merging deltas to main specs

Capabilities

Modified Capabilities

• artifact-graph: Extend artifact schema with new optional fields for spec structure configuration
• cli-validate: Validation must use artifact-defined spec format instead of hardcoded expectations

Impact

Code Areas

Parsers (high impact):

• src/core/parsers/markdown-parser.ts - section detection
• src/core/parsers/requirement-blocks.ts - requirement extraction, delta parsing
• src/core/parsers/change-parser.ts - rename format parsing

Validation (high impact):

• src/core/validation/validator.ts - spec validation rules
• src/core/validation/constants.ts - error messages
• src/commands/validate.ts - user guidance, hardcoded spec.md path
• src/commands/change.ts - help messages with hardcoded format

Discovery (medium impact):

• src/utils/item-discovery.ts - getSpecIds() only looks for spec.md, needs to read all files per schema

Generation/Sync (high impact):

• src/core/specs-apply.ts - skeleton generation, delta merge
• src/core/templates/skill-templates.ts - LLM prompts contain hardcoded delta format (## ADDED Requirements, etc.), scenario patterns (#### Scenario:), and requirement patterns. These prompts tell the AI how to generate specs.
• src/commands/schema.ts - hardcoded example spec format

Schema system (medium impact):

• src/core/artifact-graph/types.ts - extend ArtifactSchema with new fields
• src/core/artifact-graph/schema.ts - load new artifact fields

Templates (medium impact):

• schemas/spec-driven/templates/spec.md - hardcoded format, should use schema config
• schemas/spec-driven/schema.yaml - add explicit default values for new artifact fields

Breaking Changes

None. All new fields are optional with defaults that maintain backward compatibility. Existing schemas work without modification.

---

Design Considerations

Three Levels of Format

There are three distinct format concerns:

┌────────────┐      ┌────────────┐      ┌────────────┐
│  Project   │ ──►  │  Internal  │ ──►  │  Project   │
│  Format    │ READ │  Format    │WRITE │  Format    │
│  (input)   │      │ (canonical)│      │  (output)  │
└────────────┘      └────────────┘      └────────────┘

1. Project Format (input): How specs exist in the project - diverse formats created by humans, other tools, or legacy systems. OpenSpec must READ these.

2. Internal Format (canonical): OpenSpec's internal representation. This is the current hardcoded format (## Requirements, ### Requirement:, etc.). This stays fixed for backward compatibility.

3. Project Format (output): How OpenSpec WRITES new specs, deltas, and modifications. Must match the project's expected format.

Key insight: The internal format doesn't change. What changes is:

• How we MAP from project format → internal format (parsing)
• How we MAP from internal format → project format (generation)

This maintains full backward compatibility - projects using the default spec-driven schema see no changes.

Spec as a Collection of Files

A "spec" is not just one file. It's a collection that varies by schema:

schema-a:               spec-driven:          schema-c:
<capability>/           <capability>/         <capability>/
├── spec.md (required)  └── spec.md           ├── requirements.md
├── verify.md (required)    (scenarios        ├── verification.md
└── .metadata (opt)          inline)          └── examples/

Elements That Need Configuration

Section headers:

• Main requirements section: ## Requirements vs ## Functional Requirements vs ## Requisitos
• Purpose section: ## Purpose vs ## Overview vs custom

Requirement identification:

• Pattern: ### Requirement: {name} vs ### Req: {name} vs ## RF-001: {name}

Scenarios/Verification:

• Location: inline in spec.md, separate file (e.g., verify.md), or none
• Header pattern: #### Scenario: vs ### Scenario: vs Given/When/Then blocks
• Required or optional
• Note: Current validation assumes scenarios are inline in spec.md. Other schemas may have verification in separate files or not at all. Validation must respect this.

Delta format:

• Section suffix: ADDED Requirements vs ADDED Functional Requirements
• Whether deltas use same header as main spec or fixed format

File composition:

• Which files make up a complete spec
• Which are required vs optional

Schema Structure: Before and After

BEFORE (current schema.yaml):

name: custom-schema
version: 1
description: "..."

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    instruction: |
      ...
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    template: spec.md
    instruction: |
      ...
    requires: [proposal]

  # ... more artifacts

apply:
  requires: [tasks]
  tracks: tasks.md

The schema defines the workflow (artifacts), but spec structure is hardcoded in OpenSpec's parsers and validators.

---

AFTER (extended schema with validation config):

name: custom-schema
version: 1
description: "..."

# NEW: Validation configuration at schema level
changeValidation:
  artifact: "verify"                         # which artifact verifies changes

specValidation:
  artifact: "spec-verify"                    # which artifact contains scenarios
  pattern: "### Scenario: {name}"            # how to identify scenarios
  required: true                             # whether scenarios are mandatory

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    instruction: |
      ...
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    template: spec.md
    instruction: |
      ...
    requires: [proposal]

    # NEW: Extended artifact configuration (structure only, no scenarios)
    sections:
      required: ["Purpose", "Functional Requirements"]
      optional: ["Scope", "Status", "Definitions", "Constraints"]
      requirement:
        section: "Functional Requirements"     # which section contains requirements
        pattern: "### Requirement: {name}"     # how to identify requirements

  - id: spec-verify
    generates: "specs/**/verify.md"            # output artifact: synced to specs/
    template: spec-verify.md
    instruction: |
      ...
    requires: [specs]
    sections:
      required: ["Acceptance Criteria", "Test Scenarios"]
      optional: ["Verification Methods", "Failure Conditions"]

  - id: verify
    generates: verify.md                       # workflow artifact: NOT synced
    template: verify.md
    instruction: |
      ...
    requires: [specs]
    # Referenced by changeValidation.artifact

  - id: design
    generates: design.md
    template: design.md
    requires: [proposal]

  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [specs, design]

apply:
  requires: [tasks]
  tracks: tasks.md

Two new schema-level blocks (changeValidation, specValidation) plus extended artifact fields for structure.

All new fields are optional. When omitted, OpenSpec uses defaults that match current spec-driven behavior. Existing schemas work without modification.

New Schema Fields Specification

The following fields are added to the schema. All fields are optional with backward-compatible defaults—existing schemas continue to work without modification.

Schema-Level Validation Config

# New schema-level fields
changeValidation:
  artifact: string                      # Which artifact verifies change implementation

specValidation:
  artifact: string                      # Which artifact contains scenarios (e.g., "specs" or "spec-verify")
  pattern: string                       # Pattern to identify scenarios (e.g., "#### Scenario: {name}")
  required: boolean                     # Whether scenarios are mandatory
  shallMustPattern: string | null       # Regex pattern for normative keywords (e.g., "SHALL|MUST"), null to disable

Artifact-Level Structure Config

# New fields for artifact definition
artifacts:
  - id: string              # existing
    generates: string       # existing
    template: string        # existing
    instruction: string     # existing (optional)
    requires: string[]      # existing

    # NEW FIELDS:

    sections:                           # Section configuration
      required: string[]                # Sections that MUST exist (e.g., ["Purpose", "Requirements"])
      optional: string[]                # Sections that MAY exist (for documentation)
      requirement:                      # Requirement block configuration (only for spec artifacts)
        section: string                 # Which section contains requirements (e.g., "Functional Requirements")
        pattern: string                 # Pattern to identify requirements (e.g., "### Requirement: {name}")

Field Details:

Field	Type	Default	Description
changeValidation.artifact	string	"verify"	Artifact that verifies change implementation
specValidation.artifact	string	"specs"	Artifact containing scenarios ("specs" = inline)
specValidation.pattern	string	"#### Scenario: {name}"	Pattern to identify scenario blocks
specValidation.required	boolean	true	Whether validation fails if no scenarios found
specValidation.shallMustPattern	string | null	"SHALL|MUST"	Regex pattern for normative keywords; null or empty to disable
sections.required	string[]	["Purpose", "Requirements"]	Section headers that must exist
sections.optional	string[]	[]	Section headers that are recognized but optional
sections.requirement.section	string	"Requirements"	Section containing requirements (used for delta operations)
sections.requirement.pattern	string	"### Requirement: {name}"	Pattern to identify requirement blocks

shallMustPattern Examples:

# Default: strict uppercase (RFC 2119 style)
shallMustPattern: "SHALL|MUST"
# Matches: "The system SHALL validate input"
# Matches: "Users MUST authenticate"
# Fails:   "The system should validate input"

# Case-insensitive: accepts lowercase variants
shallMustPattern: "[Ss][Hh][Aa][Ll][Ll]|[Mm][Uu][Ss][Tt]"
# Matches: "The system shall validate input"
# Matches: "Users must authenticate"
# Matches: "The system SHALL validate input"

# Extended: include SHOULD for less strict requirements
shallMustPattern: "SHALL|MUST|SHOULD"
# Matches: "The system SHOULD log errors"

# Spanish: for Spanish-language specifications
shallMustPattern: "DEBE|DEBERÁ|TIENE QUE"
# Matches: "El sistema DEBE validar la entrada"

# Disabled: no normative keyword validation
shallMustPattern: null
# or
shallMustPattern: ""
# All requirements pass regardless of wording

Delta sections are derived from sections.requirement.section:

• If sections.requirement.section: "Functional Requirements", deltas use ## ADDED Functional Requirements, ## MODIFIED Functional Requirements, etc.

Workflow vs Output Artifacts

The current artifact system already supports distinguishing between:

1. Workflow artifacts (temporary, for the change process)
2. Output artifacts (permanent, synced to specs/)

Example:

artifacts:
  - id: verify
    generates: verify.md
    # Workflow artifact: verifies the change implementation
    # Lives at: <change>/verify.md
    # NOT synced to specs/

  - id: spec-verify
    generates: "specs/**/verify.md"
    # Output artifact: verification for each capability
    # Lives at: <change>/specs/<cap>/verify.md
    # Synced to: specs/<scope>/<cap>/verify.md

The generates pattern determines behavior:

• generates: verify.md → single file at change root (workflow)
• generates: "specs/**/verify.md" → files alongside specs (output, synced)

Change Validation vs Spec Validation

Two distinct validation concerns, configured at schema level:

# How changes are verified (during development)
changeValidation:
  artifact: "verify"                   # uses <change>/verify.md

# How specs are validated (structure validation)
specValidation:
  artifact: "specs"                    # scenarios in spec.md (inline)
  pattern: "#### Scenario: {name}"
  required: true

Or with separate verification files:

changeValidation:
  artifact: "verify"                   # uses <change>/verify.md

specValidation:
  artifact: "spec-verify"              # scenarios in verify.md (separate)
  pattern: "### Scenario: {name}"
  required: true

Key distinction:

• changeValidation → which artifact verifies that implementation matches change requirements
• specValidation → which artifact contains scenarios for validating spec structure

Reading Specs: All Files, Not Just spec.md

Currently OpenSpec treats specs as directories (openspec/specs/{id}/) but only reads spec.md (hardcoded in validate.ts:142,209). Other files in the directory are ignored.

With this change, OpenSpec reads all files in the spec directory, matching them to output artifacts defined in the schema.

When reading/validating specs, OpenSpec should:

1. Scan the spec directory for all files
2. Match files to artifacts based on generates patterns
3. Validate presence of required files (per artifact configuration)
4. Parse each file according to its artifact's configuration

Example for a schema with specs and spec-verify artifacts:

specs/user-auth/
├── spec.md        ← matched by specs artifact (generates: "specs/**/*.md")
└── verify.md      ← matched by spec-verify artifact (generates: "specs/**/verify.md")

OpenSpec validates:

• spec.md exists (required by specs artifact)
• verify.md exists (required by spec-verify artifact)
• Each file has its required sections per artifact config

Dynamic Prompts (Schema-Aware Skills)

Skills are defined once in skill-templates.ts, but each change can use a different schema. Prompts must dynamically read format configuration instead of hardcoding values.

Current approach (hardcoded):

Use these delta sections:
- `## ADDED Requirements`
- `## MODIFIED Requirements`

New approach (schema-aware):

Before generating specs, read the schema configuration:

1. Find the change's schema: `openspec/changes/<name>/.openspec.yaml` → `schema` field
2. Load schema definition: `schemas/<schema>/schema.yaml` or `openspec/schemas/<schema>/schema.yaml`
3. Read schema-level validation config:
   - `specValidation.artifact` → which artifact has scenarios
   - `specValidation.pattern` → how to format scenario headers
   - `specValidation.required` → whether scenarios are mandatory
4. Find the `specs` artifact and read its format fields:
   - `sections.requirement.section` → use for delta headers (e.g., "Functional Requirements" → `## ADDED Functional Requirements`)
   - `sections.requirement.pattern` → how to format requirement headers

If fields are not defined, use defaults:
- `specValidation.artifact`: "specs" (inline)
- `specValidation.pattern`: "#### Scenario: {name}"
- `specValidation.required`: true
- `sections.requirement.section`: "Requirements"
- `sections.requirement.pattern`: "### Requirement: {name}"

This approach:

• Works with existing skill architecture (no code changes to skill loading)
• Lets the AI adapt to any schema at runtime
• Maintains backward compatibility (defaults match current behavior)

Default Values (backward compatible)

When extended fields are omitted, OpenSpec uses these defaults (matching current spec-driven behavior):

# Default schema-level validation config
changeValidation:
  artifact: "verify"

specValidation:
  artifact: "specs"                      # scenarios inline in spec.md
  pattern: "#### Scenario: {name}"
  required: true
  shallMustPattern: "SHALL|MUST"         # regex pattern for normative keywords (null to disable)

# Default for specs artifact
artifacts:
  - id: specs
    sections:
      required: ["Purpose", "Requirements"]
      requirement:
        section: "Requirements"
        pattern: "### Requirement: {name}"

[lsmonki]

Proposal Update: Added shallMustPattern configuration

Added a new field specValidation.shallMustPattern to allow configurable normative keyword validation.

Changes

New field: specValidation.shallMustPattern: string | null

• Regex pattern to validate normative keywords in requirements
• Default: "SHALL|MUST" (RFC 2119 uppercase)
• Set to null or "" to disable validation

Use cases

• Default (RFC 2119 strict)
  shallMustPattern: "SHALL|MUST"

• Case-insensitive
  shallMustPattern: "[Ss][Hh][Aa][Ll][Ll]|[Mm][Uu][Ss][Tt]"

• Or simpler: "must|MUST|shall|SHALL"

• Spanish specs
  shallMustPattern: "DEBE|DEBERÁ|TIENE QUE"

• Disable validation
  shallMustPattern: null

Rationale

Projects with existing specs may use different conventions:

• Lowercase keywords (must, shall)
• Keywords in non-English languages
• No strict keyword requirements

This makes OpenSpec adaptable to diverse spec formats without forcing migration to uppercase RFC 2119 style.

[lsmonki]

After further exploration, we identified limitations in the original design that prevent it from supporting multi-file specs and generalized delta merge. This update proposes changes to the artifact-level configuration.

---

Summary of Changes

Aspect	Original Design (#666)	Updated Design
Delta config	sections.requirement (singular, hardcoded to "requirement")	deltas[] (array, generic — any artifact can define mergeable blocks)
Structural validation	Not covered (no artifact-level validation config)	validations[] at artifact level (each artifact defines its own structural rules)
Required sections	sections.required[] / sections.optional[]	Absorbed into validations[] (e.g., { pattern: "## Purpose", required: true })
Delta operations	Derived from sections.requirement.section	Derived from deltas[].section — same convention, now per-entry
Compliance naming	specValidation / changeValidation	Renamed to specVerify / changeVerify — avoids confusion with validations[]

---

Key Design Decisions

1. deltas[] replaces sections.requirement

Problem: The original sections.requirement was singular and named after "requirement". A verify.md artifact with ### Verification: {name} blocks wouldn't fit this model.

Solution: deltas is an array of block definitions. Each entry defines a mergeable section with its own pattern. The delta operations (ADDED/MODIFIED/REMOVED/RENAMED) are derived from the section name.

# Original (singular, hardcoded name)
sections:
  requirement:
    section: "Requirements"
    pattern: "### Requirement: {name}"

# Updated (array, generic)
deltas:
  - section: "Requirements"
    pattern: "### Requirement: {name}"
  - section: "Constraints"
    pattern: "### Constraint: {name}"

Delta operations are derived: ## {ADDED|MODIFIED|REMOVED|RENAMED} {section}.

An artifact can have multiple delta sections. An artifact without deltas (like design.md) has no delta merge — it gets copied as-is during sync.

2. validations[] at artifact level for structural checks

Problem: The original design had no mechanism for per-artifact structural validation. Structural checks (does the file have the right sections? does it use the right patterns?) were either hardcoded or absent.

Solution: Each artifact can define validations[] — pattern-existence rules with three granularity levels.

Granularity levels:

Field	Meaning	Example
(none)	Pattern must exist somewhere in the file	## Purpose exists
scope	Pattern must exist somewhere within a ## section	Some pattern exists within ## Requirements
eachBlock	Pattern must exist in each ### block within a ## section	Every ### Requirement: block contains SHALL|MUST

scope and eachBlock reference a section name. Blocks are determined by the next markdown heading level (a ## section is split into ### blocks).

validations:
  # File-level: section must exist in the file
  - pattern: "## Purpose"
    required: true

  # Section-level: pattern must exist somewhere within ## Requirements
  - pattern: "### Requirement: {name}"
    required: true
    scope: "Requirements"

  # Block-level: pattern must exist in EACH ### block within ## Requirements
  - pattern: "SHALL|MUST"
    required: true
    eachBlock: "Requirements"

  - pattern: "#### Scenario: {name}"
    required: true
    eachBlock: "Requirements"

3. sections.required / sections.optional absorbed into validations

Required sections are just a validation rule:

# Original
sections:
  required: ["Purpose", "Requirements"]
  optional: ["Scope", "Definitions"]

# Updated — same result, one mechanism
validations:
  - pattern: "## Purpose"
    required: true
  - pattern: "## Requirements"
    required: true

No need for a separate sections concept. validations handles it.

---

Combined Design (Issue #666 + This Update)

This is the full schema specification combining the original issue #666 with the updates proposed here.

Schema-Level Fields

# Compliance validation: how to verify implementation matches specs
# (from issue #666, unchanged)
specVerify:
  artifact: string              # which artifact contains verification criteria
  pattern: string               # pattern to identify verification blocks
  required: boolean             # whether verification is mandatory
  shallMustPattern: string|null # regex for normative keywords, null to disable

# Change validation: which artifact verifies the change
# (from issue #666, unchanged)
changeVerify:
  artifact: string              # which artifact verifies change implementation

Artifact-Level Fields

artifacts:
  - id: string                  # existing
    generates: string           # existing — determines sync behavior:
                                #   "specs/**/*" → synced to openspec/specs/
                                #   anything else → workflow artifact, not synced
    template: string            # existing
    instruction: string         # existing (optional)
    requires: string[]          # existing

    # NEW: Delta merge configuration (array, optional)
    deltas:
      - section: string         # section name (e.g., "Requirements")
        pattern: string         # block pattern (e.g., "### Requirement: {name}")
                                # Delta operations derived: ## {ADDED|MODIFIED|REMOVED|RENAMED} {section}

    # NEW: Structural validation rules (array, optional)
    validations:
      - pattern: string         # pattern to search for
        required: boolean       # whether it must exist
        scope: string           # (optional) validate within a ## section
        eachBlock: string       # (optional) validate within EACH ### block of a ## section

Validation Granularity

Field	Searches in	Use case
(none)	Entire file	Required sections: ## Purpose
scope: "X"	Within ## X section	At least one block exists
eachBlock: "X"	Each ### block within ## X	Every block has scenarios, uses SHALL/MUST

Multi-File Spec Behavior

A "spec" is a folder. Any artifact whose generates starts with specs/ produces files that sync to the main specs folder on archive:

• Files with deltas config → delta merge (ADDED/MODIFIED/REMOVED/RENAMED)
• Files without deltas → direct copy

Reading a spec means reading ALL files in its folder, not just spec.md.

Dynamic Prompts

Skills read format configuration from the schema at runtime instead of hardcoding patterns. Before generating specs or deltas, the AI reads:

1. deltas[].section → delta section headers (e.g., ## ADDED Requirements)
2. deltas[].pattern → block format (e.g., ### Requirement: {name})
3. validations[] → what structural rules to follow
4. specVerify → where verification criteria live

Complete Default Schema

When all new fields are omitted, OpenSpec behaves exactly as today:

name: spec-driven
version: 1
description: Default OpenSpec workflow

# Schema-level (implicit defaults)
changeVerify:
  artifact: "verify"

specVerify:
  artifact: "specs"
  pattern: "#### Scenario: {name}"
  required: true
  shallMustPattern: "SHALL|MUST"

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    template: spec.md
    requires: [proposal]
    # Implicit defaults:
    deltas:
      - section: "Requirements"
        pattern: "### Requirement: {name}"
    validations:
      - pattern: "## Purpose"
        required: true
      - pattern: "## Requirements"
        required: true
      - pattern: "### Requirement: {name}"
        required: true
        scope: "Requirements"
      - pattern: "#### Scenario: {name}"
        required: true
        eachBlock: "Requirements"
      - pattern: "SHALL|MUST"
        required: true
        eachBlock: "Requirements"

  - id: design
    generates: design.md
    template: design.md
    requires: [proposal]

  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [specs, design]

apply:
  requires: [tasks]
  tracks: tasks.md

Code Impact (Complete)

Parsers (high impact):

• src/core/parsers/markdown-parser.ts — configurable section detection
• src/core/parsers/requirement-blocks.ts — accept section and pattern params instead of hardcoded values
• src/core/parsers/change-parser.ts — use delta config for parsing

Validation (high impact):

• src/core/validation/validator.ts — read validations[] from artifact config, implement scope/eachBlock
• src/core/validation/constants.ts — error messages reference hardcoded section/block names
• src/commands/validate.ts — load schema config, validate all files in spec folder

Commands (medium impact):

• src/commands/spec.ts — hardcodes spec.md path and Requirements section parsing

Discovery (medium impact):

• src/utils/item-discovery.ts — discover all files in spec folders, not just spec.md

Sync/Archive (high impact):

• src/core/specs-apply.ts — discover all output artifacts, delta merge or direct copy per config
• src/core/archive.ts — sync all output artifacts to main specs

Schema system (medium impact):

• src/core/artifact-graph/types.ts — add deltas and validations to ArtifactSchema
• src/core/artifact-graph/schema.ts — load and default new fields
• src/core/artifact-graph/instruction-loader.ts — template path resolution references hardcoded filenames

Generation (high impact):

• src/core/templates/skill-templates.ts — dynamic prompts read format from schema; verify skill reads specVerify for compliance checks instead of hardcoded #### Scenario:
• src/commands/schema.ts — use schema config for examples and defaults

[lsmonki]

A new change... sorry.

My last comment proposed keeping both specVerify and changeVerify at schema level, alongside the new deltas[] and validations[] at artifact level. After further analysis, I think that design has some redundancies and gaps. Here's what I'd change and why.

---

1. specValidation / specVerify should be eliminated

I renamed specValidation to specVerify and proposed:

specVerify:
  artifact: "specs"
  pattern: "#### Scenario: {name}"
  required: true
  shallMustPattern: "SHALL|MUST"

Two problems:

The rename is wrong. specValidation validates the structure of spec files (openspec validate --specs): "does each requirement have scenarios?", "does each requirement use normative keywords?". That's validation, not verification. Renaming it to specVerify conflates it with changeVerify, which is actual verification — checking that implementation matches the spec. The naming confusion is a signal that the concepts are tangled.

It's redundant with validations[]. Everything specValidation configures can be expressed as eachBlock rules on the artifact:

# These two validations[] entries replace specValidation entirely:
validations:
  - pattern: "#### Scenario: {name}"
    required: true
    eachBlock: "Requirements"
  - pattern: "SHALL|MUST"
    required: true
    eachBlock: "Requirements"

Having both mechanisms means two sources of truth for the same validation. If they disagree, the code has to decide which one wins. validations[] is strictly more expressive (it supports file-level, scope-level, and eachBlock-level granularity), and specValidation adds nothing that can't be expressed there. Better to eliminate it.

2. changeVerify should be enriched

I proposed changeVerify with just artifact: string. But the verify skill (/opsx:verify) needs to know how to extract requirements and scenarios from spec files — it can't just know where they are.

Proposed design:

changeVerify:
  artifact: "specs"                            # which artifact to verify against
  requirementPattern: "### Requirement: {name}" # how to extract requirement names
  scenarioPattern: "#### Scenario: {name}"      # how to extract scenario names

This is a different concern from validations[]:

Mechanism	Purpose	Used by
validations[]	"Is this spec well-formed?"	openspec validate --specs
changeVerify.scenarioPattern / shallMustPattern	"Are the delta blocks well-formed?"	openspec validate --changes
changeVerify.artifact / requirementPattern / scenarioPattern	"How do I extract data to verify implementation against code?"	/opsx:verify

validations[] checks spec structure. changeVerify would serve two roles: its patterns validate delta block quality during change validation, and its extraction patterns let the verify skill cross-reference specs against code.

3. requiredSpecArtifacts is needed

Not present in the previous comment. I need to answer: "which artifact files must exist in each spec folder?"

requiredSpecArtifacts: [specs, verify]  # default: [specs]

This would drive all runtime file discovery — openspec validate, spec sync, archive, and spec listing. Without it, the runtime has spec.md hardcoded in 5 different places.

Each ID maps to an artifact definition, and the filename would be resolved from generates (last concrete path segment) with fallback to template. Example: artifact with generates: "specs/**/verify.md" resolves to verify.md.

4. validations[].required should control severity, not skip

My previous design has required: boolean on validation rules but doesn't specify what required: false means. If treated as "skip this rule entirely", the field is pointless — why declare a rule just to ignore it?

Proposed behavior:

required	Severity	Message	Effect on openspec validate
true	ERROR	"missing required pattern"	Blocks validation (exit code 1)
false	WARNING	"missing recommended pattern"	Informational (doesn't block)

This lets schemas express soft guidelines alongside hard constraints:

validations:
  # Hard constraint — blocks validation
  - pattern: "## Purpose"
    required: true

  # Soft guideline — warns but doesn't block
  - pattern: "## Glossary"
    required: false

---

Complete proposed design

Full schema specification with all fields documented.

Schema-level fields

# How to verify that implementation matches specs.
# Used by /opsx:verify (all fields) and openspec validate --changes (scenarioPattern).
changeVerify:
  artifact: string              # which artifact to verify against (default: "specs")
  requirementPattern: string    # how to extract requirement names (default: "### Requirement: {name}")
  scenarioPattern: string       # how to extract scenario names (default: "#### Scenario: {name}")

# Which artifact IDs must exist in each spec folder.
# Drives file discovery for validate, sync, archive, and spec listing.
requiredSpecArtifacts: string[] # (default: ["specs"])

Artifact-level fields

artifacts:
  - id: string           # artifact identifier
    generates: string    # output path pattern — determines sync behavior:
                         #   "specs/**/*" → synced to openspec/specs/ on archive
                         #   anything else → workflow artifact, not synced
    template: string     # template filename (also used for filename resolution fallback)
    description: string
    instruction: string  # (optional) prompt instructions for AI generation
    requires: string[]   # dependency IDs

    # Delta merge configuration (optional array).
    # Each entry defines a mergeable section with ADDED/MODIFIED/REMOVED/RENAMED operations.
    # Artifacts without deltas are copied as-is during sync.
    deltas:
      - section: string  # section name (e.g., "Requirements", "Constraints")
        pattern: string  # block pattern, must include {name} (e.g., "### Requirement: {name}")

    # Structural validation rules (optional array).
    # Used by openspec validate --specs. Three granularity levels.
    validations:
      - pattern: string    # pattern to search for (regex or {name} placeholder)
        required: boolean  # true → ERROR if missing, false → WARNING if missing
        scope: string      # (optional) validate within a ## section
        eachBlock: string  # (optional) validate in each ### block within a ## section
                           # scope and eachBlock are mutually exclusive

Validation granularity

Field	Searches in	Example use case
(none)	Entire file	## Purpose section exists
scope: "X"	Within ## X section	At least one ### Requirement: block exists
eachBlock: "X"	Each ### block within ## X	Every requirement has #### Scenario: and SHALL|MUST

Multi-file spec behavior

A "spec" is a folder. requiredSpecArtifacts declares which artifacts must exist in it. Each artifact's filename is resolved from generates (last concrete path segment, e.g., specs/**/verify.md → verify.md) with fallback to template when the last segment has wildcards (e.g., specs/**/*.md → use template value).

During sync/archive:

• Files with deltas[] → delta merge (ADDED/MODIFIED/REMOVED/RENAMED operations)
• Files without deltas[] → direct copy

Default schema (when all new fields are omitted)

name: spec-driven
version: 1

changeVerify:
  artifact: "specs"
  requirementPattern: "### Requirement: {name}"
  scenarioPattern: "#### Scenario: {name}"

requiredSpecArtifacts: ["specs"]

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    description: Change proposal
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    template: spec.md
    description: Specifications
    requires: [proposal]
    # Implicit defaults when omitted:
    deltas:
      - section: "Requirements"
        pattern: "### Requirement: {name}"
    validations:
      - pattern: "## Purpose"
        required: true
      - pattern: "## Requirements"
        required: true
      - pattern: "### Requirement: {name}"
        required: true
        scope: "Requirements"
      - pattern: "#### Scenario: {name}"
        required: true
        eachBlock: "Requirements"
      - pattern: "SHALL|MUST"
        required: true
        eachBlock: "Requirements"

  - id: design
    generates: design.md
    template: design.md
    description: Design document
    requires: [proposal]

  - id: tasks
    generates: tasks.md
    template: tasks.md
    description: Implementation tasks
    requires: [specs, design]

apply:
  requires: [tasks]
  tracks: tasks.md

Existing schemas without the new fields would work exactly as before — all defaults preserve current behavior.

---

I'm working on an implementation that follows this design, but as the README says: "Larger changes — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins." — so I'd rather discuss the approach here before opening a PR. Happy to submit one whenever you're ready.

[flemming-n-larsen]

Use case: Test traceability via stable criterion IDs

Currently there's no way to assign stable, machine-readable IDs to scenarios. This makes it impossible to build a CI gate that enforces every acceptance criterion has a corresponding test.

A simple convention like prefixing scenarios with an ID would unlock this:

#### Scenario [AUTH-SESSION-001]: Default session timeout
- GIVEN a user has authenticated
- WHEN 24 hours pass without activity
- THEN invalidate the session token

Tests could then reference the ID directly:

describe("[AUTH-SESSION-001] Default session timeout", () => {
  it("invalidates the session token after 24h inactivity", () => { ... })
})

A CI script could then parse openspec/specs/ for all criterion IDs and verify each one has a tagged test — failing the build if any criterion is untraced. This pattern is familiar from tools like Robot Framework, Cucumber, and Jira Xray, so many teams would know how to plug into it.

This would be a natural extension of the spec format once #666 allows configurable spec structure. The ID field could be optional, preserving full backward compatibility for teams that don't need traceability.