fix(validate): reject a delta spec at the change's specs/ root (#1385)

A `spec.md` written directly under a change's `specs/` directory was
accepted by `validate` — including `--strict` — but skipped by the
apply/archive merge, which only reads capability folders. The change
validated clean, archived successfully, and its requirements never
reached `openspec/specs/`.

Point the validator at the shared `discoverSpecFiles` helper so it applies
exactly the merge path's rules, and report a root-level `specs/spec.md` as
an error naming the capability-folder convention. Archive's delta-detection
gate now also sees that file, so validation runs and blocks the archive
instead of completing with the delta dropped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: clay-good

.changeset/root-level-delta-spec.md

@@ -0,0 +1,7 @@
+---
+"@fission-ai/openspec": patch
+---
+
+### Fixed
+
+- Stop a delta spec written directly at a change's `specs/` root from being silently dropped. `validate` accepted `specs/spec.md` and counted its deltas, but the apply/archive merge only reads capability folders (`specs/<capability>/spec.md`), so the change could pass validation and be archived while its requirements never reached `openspec/specs/`. `validate` now uses the same discovery rules as the merge path and reports the misplaced file with a fix hint, and `archive` blocks instead of completing.

src/core/archive.ts

@@ -267,7 +267,15 @@ export class ArchiveCommand {
       // Validate delta-formatted spec files under the change directory if present
       const changeSpecsDir = path.join(changeDir, 'specs');
       let hasDeltaSpecs = false;
-      for (const { specFile } of await discoverSpecFiles(changeSpecsDir)) {
+      // The root-level specs/spec.md is not a mergeable delta, but it must
+      // still trigger validation: otherwise a change whose only delta sits
+      // there skips this gate and archives with its requirements dropped
+      // (#1385). Validation reports it as an error and blocks the archive.
+      const deltaCandidates = [
+        ...(await discoverSpecFiles(changeSpecsDir)).map(spec => spec.specFile),
+        path.join(changeSpecsDir, 'spec.md'),
+      ];
+      for (const specFile of deltaCandidates) {
         try {
           const content = await fs.readFile(specFile, 'utf-8');
           if (/^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/m.test(content)) {

src/core/validation/validator.ts

@@ -18,6 +18,7 @@ import {
 } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { discoverSpecFiles } from '../../utils/spec-discovery.js';
 
 export class Validator {
   private strictMode: boolean;
@@ -125,11 +126,25 @@ export class Validator {
     const emptySectionSpecs: Array<{ path: string; sections: string[] }> = [];
 
     try {
-      // Discover delta specs at any depth so the nested multi-area layout
-      // (specs/<area>/<capability>/spec.md) is validated, not just the
-      // one-level specs/<capability>/spec.md layout (#1182b). The spec-driven
-      // specs glob is specs/**/*.md; delta files are always named spec.md.
-      const specFiles = await this.findDeltaSpecFiles(specsDir);
+      // Discover delta specs through the same helper the change parser, show,
+      // apply, and archive use, so validate never accepts a layout the merge
+      // path silently skips (#1385). It finds spec.md at any depth, covering
+      // both specs/<capability>/spec.md and the nested multi-area
+      // specs/<area>/<capability>/spec.md layout (#1182b).
+      const specFiles = (await discoverSpecFiles(specsDir)).map(spec => spec.specFile);
+
+      // A spec.md directly at the specs/ root has no capability folder, so the
+      // merge path drops it: without this error the change validates clean and
+      // archives while its requirements never reach openspec/specs/ (#1385).
+      if (await FileSystemUtils.fileExists(path.join(specsDir, 'spec.md'))) {
+        issues.push({
+          level: 'ERROR',
+          path: 'spec.md',
+          message:
+            'Delta spec found at specs/spec.md. Delta specs must live in a capability folder (e.g. specs/<capability>/spec.md) — a file at the specs/ root is ignored when the change is applied or archived.',
+        });
+      }
+
       for (const specFile of specFiles) {
         let content: string | undefined;
         try {
@@ -310,34 +325,6 @@ export class Validator {
     return this.createReport(issues);
   }
 
-  /**
-   * Recursively collect every delta `spec.md` under a change's specs directory,
-   * so both the one-level (specs/<capability>/spec.md) and nested multi-area
-   * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
-   * Returns absolute paths, sorted for deterministic issue ordering.
-   */
-  private async findDeltaSpecFiles(specsDir: string): Promise<string[]> {
-    const results: string[] = [];
-    const walk = async (dir: string): Promise<void> => {
-      let entries;
-      try {
-        entries = await fs.readdir(dir, { withFileTypes: true });
-      } catch {
-        return;
-      }
-      for (const entry of entries) {
-        const full = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          await walk(full);
-        } else if (entry.isFile() && entry.name === 'spec.md') {
-          results.push(full);
-        }
-      }
-    };
-    await walk(specsDir);
-    return results.sort();
-  }
-
   private convertZodErrors(error: ZodError): ValidationIssue[] {
     return error.issues.map(err => {
       let message = err.message;

test/core/archive.test.ts

@@ -1062,6 +1062,37 @@ The system will log all events.
       expect(archives.some(a => a.includes(changeName))).toBe(false);
     });
 
+    it('sets exit code 1 when the only delta spec sits at the specs/ root (#1385)', async () => {
+      const changeName = 'exit-root-delta';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecsDir = path.join(changeDir, 'specs');
+      await fs.mkdir(changeSpecsDir, { recursive: true });
+
+      // No capability folder: the merge path skips this file, so archiving it
+      // used to succeed while dropping the requirement.
+      const specContent = `## ADDED Requirements
+
+### Requirement: Request metrics
+The system SHALL record request metrics.
+
+#### Scenario: Request is counted
+- **WHEN** a request completes
+- **THEN** a counter is incremented`;
+      await fs.writeFile(path.join(changeSpecsDir, 'spec.md'), specContent);
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), '- [x] Task 1\n');
+
+      await archiveCommand.execute(changeName, { yes: true });
+
+      expect(process.exitCode).toBe(1);
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Validation failed')
+      );
+
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.some(a => a.includes(changeName))).toBe(false);
+    });
+
     it('sets exit code 1 when spec rebuild fails (MODIFIED on new spec)', async () => {
       const changeName = 'exit-rebuild-fail';
       const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);

test/core/validation.test.ts

@@ -506,6 +506,57 @@ The system SHALL handle all errors gracefully.
       expect(report.summary.errors).toBe(0);
     });
 
+    it('should fail when a delta spec.md sits directly under specs/', async () => {
+      // #1385: the merge path only reads specs/<capability>/spec.md, so a
+      // root-level file used to validate clean and then archive with its
+      // requirements silently dropped.
+      const changeDir = path.join(testDir, 'test-change-root-delta');
+      const specsDir = path.join(changeDir, 'specs');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `## ADDED Requirements
+
+### Requirement: Request metrics
+The system SHALL record request metrics.
+
+#### Scenario: Request is counted
+- **WHEN** a request completes
+- **THEN** a counter is incremented`;
+
+      await fs.writeFile(path.join(specsDir, 'spec.md'), deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(false);
+      expect(
+        report.issues.some(i => i.message.includes('Delta spec found at specs/spec.md'))
+      ).toBe(true);
+    });
+
+    it('should still validate a nested capability layout', async () => {
+      const changeDir = path.join(testDir, 'test-change-nested-delta');
+      const specsDir = path.join(changeDir, 'specs', 'platform', 'metrics');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      const deltaSpec = `## ADDED Requirements
+
+### Requirement: Request metrics
+The system SHALL record request metrics.
+
+#### Scenario: Request is counted
+- **WHEN** a request completes
+- **THEN** a counter is incremented`;
+
+      await fs.writeFile(path.join(specsDir, 'spec.md'), deltaSpec);
+
+      const validator = new Validator(true);
+      const report = await validator.validateChangeDeltaSpecs(changeDir);
+
+      expect(report.valid).toBe(true);
+      expect(report.summary.errors).toBe(0);
+    });
+
     it('should fail when requirement text lacks SHALL/MUST', async () => {
       const changeDir = path.join(testDir, 'test-change-3');
       const specsDir = path.join(changeDir, 'specs', 'test-spec');