From dca846ec0635ef00b0572dfae2d82257fa5e5ea5 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Fri, 15 May 2026 16:53:40 -0700
Subject: [PATCH 1/3] fix: validate artifact content before marking workflow
 step done

Closes #1084
---
 .changeset/validate-artifact-content.md  |  7 +++
 src/core/artifact-graph/outputs.ts       | 33 +++++++++++++++
 src/core/artifact-graph/state.ts         | 10 ++---
 test/core/artifact-graph/outputs.test.ts | 43 ++++++++++++++++++-
 test/core/artifact-graph/state.test.ts   | 54 ++++++++++++++++++++++++
 5 files changed, 141 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/validate-artifact-content.md

diff --git a/.changeset/validate-artifact-content.md b/.changeset/validate-artifact-content.md
new file mode 100644
index 000000000..53c2f7f5c
--- /dev/null
+++ b/.changeset/validate-artifact-content.md
@@ -0,0 +1,7 @@
+---
+"@fission-ai/openspec": patch
+---
+
+### Bug Fixes
+
+- Fixed workflow resumes so empty or whitespace-only artifact files are regenerated instead of being treated as completed.
diff --git a/src/core/artifact-graph/outputs.ts b/src/core/artifact-graph/outputs.ts
index 9467552f2..e0a7f8747 100644
--- a/src/core/artifact-graph/outputs.ts
+++ b/src/core/artifact-graph/outputs.ts
@@ -40,3 +40,36 @@ export function resolveArtifactOutputs(changeDir: string, generates: string): st
 export function artifactOutputExists(changeDir: string, generates: string): boolean {
   return resolveArtifactOutputs(changeDir, generates).length > 0;
 }
+
+/**
+ * Checks if all resolved artifact output files contain meaningful content.
+ */
+export function artifactOutputContentValid(changeDir: string, generates: string): boolean {
+  const outputs = resolveArtifactOutputs(changeDir, generates);
+
+  return outputs.length > 0 && outputs.every(isArtifactOutputFileContentValid);
+}
+
+/**
+ * Checks if an artifact has resolved output files and each contains meaningful content.
+ */
+export function artifactOutputComplete(changeDir: string, generates: string): boolean {
+  return artifactOutputExists(changeDir, generates)
+    && artifactOutputContentValid(changeDir, generates);
+}
+
+function isArtifactOutputFileContentValid(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    return content
+      .split(/\r?\n/)
+      .some((line) => {
+        const trimmed = line.trim();
+
+        return trimmed.length > 0 && !trimmed.startsWith('<!--');
+      });
+  } catch {
+    return false;
+  }
+}
diff --git a/src/core/artifact-graph/state.ts b/src/core/artifact-graph/state.ts
index 47c256ac9..dfe3aa0bf 100644
--- a/src/core/artifact-graph/state.ts
+++ b/src/core/artifact-graph/state.ts
@@ -1,15 +1,15 @@
 import * as fs from 'node:fs';
 import type { CompletedSet } from './types.js';
 import type { ArtifactGraph } from './graph.js';
-import { artifactOutputExists } from './outputs.js';
+import { artifactOutputComplete } from './outputs.js';
 
 /**
- * Detects which artifacts are completed by checking file existence in the change directory.
+ * Detects which artifacts are completed by checking output files in the change directory.
  * Returns a Set of completed artifact IDs.
  *
  * @param graph - The artifact graph to check
  * @param changeDir - The change directory to scan for files
- * @returns Set of artifact IDs whose generated files exist
+ * @returns Set of artifact IDs whose generated files exist and contain content
  */
 export function detectCompleted(graph: ArtifactGraph, changeDir: string): CompletedSet {
   const completed = new Set<string>();
@@ -29,9 +29,9 @@ export function detectCompleted(graph: ArtifactGraph, changeDir: string): Comple
 }
 
 /**
- * Checks if an artifact is complete by checking if its generated file(s) exist.
+ * Checks if an artifact is complete by checking if its generated file(s) exist and contain content.
  * Supports both simple paths and glob patterns.
  */
 function isArtifactComplete(generates: string, changeDir: string): boolean {
-  return artifactOutputExists(changeDir, generates);
+  return artifactOutputComplete(changeDir, generates);
 }
diff --git a/test/core/artifact-graph/outputs.test.ts b/test/core/artifact-graph/outputs.test.ts
index 988200e2c..7a36f472b 100644
--- a/test/core/artifact-graph/outputs.test.ts
+++ b/test/core/artifact-graph/outputs.test.ts
@@ -3,7 +3,12 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { FileSystemUtils } from '../../../src/utils/file-system.js';
-import { artifactOutputExists, resolveArtifactOutputs } from '../../../src/core/artifact-graph/outputs.js';
+import {
+  artifactOutputComplete,
+  artifactOutputContentValid,
+  artifactOutputExists,
+  resolveArtifactOutputs,
+} from '../../../src/core/artifact-graph/outputs.js';
 
 describe('artifact-graph/outputs', () => {
   let tempDir: string;
@@ -25,6 +30,42 @@ describe('artifact-graph/outputs', () => {
 
     expect(resolveArtifactOutputs(tempDir, 'proposal.md')).toEqual([canonical(filePath)]);
     expect(artifactOutputExists(tempDir, 'proposal.md')).toBe(true);
+    expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(true);
+  });
+
+  it('keeps existence checks true for empty files while completion rejects them', () => {
+    const filePath = path.join(tempDir, 'proposal.md');
+    fs.writeFileSync(filePath, '');
+
+    expect(resolveArtifactOutputs(tempDir, 'proposal.md')).toEqual([canonical(filePath)]);
+    expect(artifactOutputExists(tempDir, 'proposal.md')).toBe(true);
+    expect(artifactOutputContentValid(tempDir, 'proposal.md')).toBe(false);
+    expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(false);
+  });
+
+  it('rejects whitespace-only artifact output content', () => {
+    fs.writeFileSync(path.join(tempDir, 'proposal.md'), ' \n\t\n');
+
+    expect(artifactOutputContentValid(tempDir, 'proposal.md')).toBe(false);
+    expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(false);
+  });
+
+  it('accepts a non-empty heading as meaningful artifact output content', () => {
+    fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal\n');
+
+    expect(artifactOutputContentValid(tempDir, 'proposal.md')).toBe(true);
+    expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(true);
+  });
+
+  it('rejects glob outputs when any resolved file lacks meaningful content', () => {
+    const specsDir = path.join(tempDir, 'specs');
+    fs.mkdirSync(specsDir, { recursive: true });
+    fs.writeFileSync(path.join(specsDir, 'feature-a.md'), '# Feature A\n');
+    fs.writeFileSync(path.join(specsDir, 'feature-b.md'), '');
+
+    expect(artifactOutputExists(tempDir, 'specs/*.md')).toBe(true);
+    expect(artifactOutputContentValid(tempDir, 'specs/*.md')).toBe(false);
+    expect(artifactOutputComplete(tempDir, 'specs/*.md')).toBe(false);
   });
 
   it('does not treat a directory as a resolved literal artifact output', () => {
diff --git a/test/core/artifact-graph/state.test.ts b/test/core/artifact-graph/state.test.ts
index 758a7675b..9a8096320 100644
--- a/test/core/artifact-graph/state.test.ts
+++ b/test/core/artifact-graph/state.test.ts
@@ -61,6 +61,45 @@ describe('artifact-graph/state', () => {
       expect(completed.has('proposal')).toBe(true);
     });
 
+    it('should not mark artifact complete when file is empty', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), '');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(false);
+    });
+
+    it('should not mark artifact complete when file is whitespace-only', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), ' \n\t\n');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(false);
+    });
+
+    it('should mark artifact complete when file contains a single heading line', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal\n');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(true);
+    });
+
     it('should not mark artifact complete when file does not exist', () => {
       const schema = createSchema([
         { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
@@ -108,6 +147,21 @@ describe('artifact-graph/state', () => {
       expect(completed.has('specs')).toBe(true);
     });
 
+    it('should not mark glob pattern complete when one matched file is empty', () => {
+      const schema = createSchema([
+        { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      fs.mkdirSync(path.join(tempDir, 'specs'), { recursive: true });
+      fs.writeFileSync(path.join(tempDir, 'specs', 'feature-a.md'), '# Feature A\n');
+      fs.writeFileSync(path.join(tempDir, 'specs', 'feature-b.md'), '');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('specs')).toBe(false);
+    });
+
     it('should not mark glob pattern complete when directory is empty', () => {
       const schema = createSchema([
         { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: [] },

From ce0c1d7ab795ae03bed8d9467001d1ab6f6a7f3e Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Fri, 15 May 2026 17:14:18 -0700
Subject: [PATCH 2/3] address CodeRabbit review: collapse double resolve, add
 comment-only tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- artifactOutputComplete now resolves outputs once instead of twice
- changeset note mentions comment-only files (matches impl behavior)
- outputs.test.ts: comment-only artifact rejected by content validator
- state.test.ts: detectCompleted excludes comment-only files

Tests: pnpm vitest run test/core/artifact-graph/ — 147 passed.
---
 .changeset/validate-artifact-content.md  |  2 +-
 src/core/artifact-graph/outputs.ts       |  6 ++++--
 test/core/artifact-graph/outputs.test.ts | 10 ++++++++++
 test/core/artifact-graph/state.test.ts   | 16 ++++++++++++++++
 4 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/.changeset/validate-artifact-content.md b/.changeset/validate-artifact-content.md
index 53c2f7f5c..20efc2253 100644
--- a/.changeset/validate-artifact-content.md
+++ b/.changeset/validate-artifact-content.md
@@ -4,4 +4,4 @@
 
 ### Bug Fixes
 
-- Fixed workflow resumes so empty or whitespace-only artifact files are regenerated instead of being treated as completed.
+- Fixed workflow resumes so empty, whitespace-only, or comment-only artifact files are regenerated instead of being treated as completed.
diff --git a/src/core/artifact-graph/outputs.ts b/src/core/artifact-graph/outputs.ts
index e0a7f8747..f810ec162 100644
--- a/src/core/artifact-graph/outputs.ts
+++ b/src/core/artifact-graph/outputs.ts
@@ -52,10 +52,12 @@ export function artifactOutputContentValid(changeDir: string, generates: string)
 
 /**
  * Checks if an artifact has resolved output files and each contains meaningful content.
+ * Resolves outputs once and reuses the result for both checks.
  */
 export function artifactOutputComplete(changeDir: string, generates: string): boolean {
-  return artifactOutputExists(changeDir, generates)
-    && artifactOutputContentValid(changeDir, generates);
+  const outputs = resolveArtifactOutputs(changeDir, generates);
+
+  return outputs.length > 0 && outputs.every(isArtifactOutputFileContentValid);
 }
 
 function isArtifactOutputFileContentValid(filePath: string): boolean {
diff --git a/test/core/artifact-graph/outputs.test.ts b/test/core/artifact-graph/outputs.test.ts
index 7a36f472b..ab3990f81 100644
--- a/test/core/artifact-graph/outputs.test.ts
+++ b/test/core/artifact-graph/outputs.test.ts
@@ -50,6 +50,16 @@ describe('artifact-graph/outputs', () => {
     expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(false);
   });
 
+  it('rejects comment-only artifact output content', () => {
+    fs.writeFileSync(
+      path.join(tempDir, 'proposal.md'),
+      '<!-- placeholder -->\n<!-- generated by workflow -->\n'
+    );
+
+    expect(artifactOutputContentValid(tempDir, 'proposal.md')).toBe(false);
+    expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(false);
+  });
+
   it('accepts a non-empty heading as meaningful artifact output content', () => {
     fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal\n');
 
diff --git a/test/core/artifact-graph/state.test.ts b/test/core/artifact-graph/state.test.ts
index 9a8096320..e08a79f23 100644
--- a/test/core/artifact-graph/state.test.ts
+++ b/test/core/artifact-graph/state.test.ts
@@ -100,6 +100,22 @@ describe('artifact-graph/state', () => {
       expect(completed.has('proposal')).toBe(true);
     });
 
+    it('should not mark artifact complete when file only contains HTML comments', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      fs.writeFileSync(
+        path.join(tempDir, 'proposal.md'),
+        '<!-- placeholder -->\n<!-- generated by workflow -->\n'
+      );
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(false);
+    });
+
     it('should not mark artifact complete when file does not exist', () => {
       const schema = createSchema([
         { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },

From e60823069e380ab974d12ce4d8cfc79f71bfba2b Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu, 21 May 2026 23:14:58 -0700
Subject: [PATCH 3/3] fix: strip HTML comment blocks before validating artifact
 content

Multi-line HTML comments like:
  <!--
  placeholder
  -->
were incorrectly treated as meaningful content because the line-based
check only skipped lines starting with '<!--'. The middle line
("placeholder") was counted as real content, so comment-only files
were marked complete.

Strip HTML comment blocks via /<!--[\s\S]*?(-->|$)/g before splitting
into lines, then any non-whitespace line counts as meaningful content.
The non-greedy (-->|$) tail handles unterminated comment blocks safely.

Add regression tests in outputs.test.ts and state.test.ts covering the
multi-line comment-only case for both artifactOutputContentValid /
artifactOutputComplete and detectCompleted.

Update the changeset to mention HTML-comment-only specifically and
note that heading-only or other partially-written artifacts are not
yet detected (heading content still counts as meaningful).

Signed-off-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
---
 .changeset/validate-artifact-content.md  |  2 +-
 src/core/artifact-graph/outputs.ts       |  9 +++------
 test/core/artifact-graph/outputs.test.ts |  7 +++++++
 test/core/artifact-graph/state.test.ts   | 13 +++++++++++++
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/.changeset/validate-artifact-content.md b/.changeset/validate-artifact-content.md
index 20efc2253..9937d65c0 100644
--- a/.changeset/validate-artifact-content.md
+++ b/.changeset/validate-artifact-content.md
@@ -4,4 +4,4 @@
 
 ### Bug Fixes
 
-- Fixed workflow resumes so empty, whitespace-only, or comment-only artifact files are regenerated instead of being treated as completed.
+- Fixed workflow resumes so empty, whitespace-only, or HTML-comment-only artifact files are regenerated instead of being treated as completed. Heading-only or other partially-written artifacts are not yet detected and may still be treated as complete.
diff --git a/src/core/artifact-graph/outputs.ts b/src/core/artifact-graph/outputs.ts
index f810ec162..0b4d2cebd 100644
--- a/src/core/artifact-graph/outputs.ts
+++ b/src/core/artifact-graph/outputs.ts
@@ -63,14 +63,11 @@ export function artifactOutputComplete(changeDir: string, generates: string): bo
 function isArtifactOutputFileContentValid(filePath: string): boolean {
   try {
     const content = fs.readFileSync(filePath, 'utf8');
+    const withoutHtmlComments = content.replace(/<!--[\s\S]*?(-->|$)/g, '');
 
-    return content
+    return withoutHtmlComments
       .split(/\r?\n/)
-      .some((line) => {
-        const trimmed = line.trim();
-
-        return trimmed.length > 0 && !trimmed.startsWith('<!--');
-      });
+      .some((line) => line.trim().length > 0);
   } catch {
     return false;
   }
diff --git a/test/core/artifact-graph/outputs.test.ts b/test/core/artifact-graph/outputs.test.ts
index ab3990f81..2bbd0d005 100644
--- a/test/core/artifact-graph/outputs.test.ts
+++ b/test/core/artifact-graph/outputs.test.ts
@@ -60,6 +60,13 @@ describe('artifact-graph/outputs', () => {
     expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(false);
   });
 
+  it('rejects multi-line comment-only artifact output content', () => {
+    fs.writeFileSync(path.join(tempDir, 'proposal.md'), '<!--\nplaceholder\n-->\n');
+
+    expect(artifactOutputContentValid(tempDir, 'proposal.md')).toBe(false);
+    expect(artifactOutputComplete(tempDir, 'proposal.md')).toBe(false);
+  });
+
   it('accepts a non-empty heading as meaningful artifact output content', () => {
     fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal\n');
 
diff --git a/test/core/artifact-graph/state.test.ts b/test/core/artifact-graph/state.test.ts
index e08a79f23..0108b658c 100644
--- a/test/core/artifact-graph/state.test.ts
+++ b/test/core/artifact-graph/state.test.ts
@@ -116,6 +116,19 @@ describe('artifact-graph/state', () => {
       expect(completed.has('proposal')).toBe(false);
     });
 
+    it('should not mark artifact complete when file only contains a multi-line HTML comment', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), '<!--\nplaceholder\n-->\n');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(false);
+    });
+
     it('should not mark artifact complete when file does not exist', () => {
       const schema = createSchema([
         { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },