Skip non-frontmatter Markdown files during compile-all workflow discovery (#27387)

* Initial plan

* fix: skip non-frontmatter markdown files during workflow compilation

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3aba940b-5a8f-4680-be99-b6aedaf23188

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* perf: tighten frontmatter prefix scan in workflow filter

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3aba940b-5a8f-4680-be99-b6aedaf23188

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* style: refine frontmatter line extraction for markdown filter

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3aba940b-5a8f-4680-be99-b6aedaf23188

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* test: tighten frontmatter filter tests and setup assertions

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3aba940b-5a8f-4680-be99-b6aedaf23188

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* test: cover frontmatter filter edge cases

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3aba940b-5a8f-4680-be99-b6aedaf23188

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* docs(adr): add draft ADR-27387 for frontmatter-based markdown filtering

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: align frontmatter discovery with parser semantics

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/d59aec7b-aba8-41e6-a13d-92a4ca0198b5

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 4 people

docs/adr/27387-filter-non-frontmatter-markdown-during-compile-all.md

@@ -0,0 +1,78 @@
+# ADR-27387: Filter Non-Frontmatter Markdown Files During compile-all Discovery
+
+**Date**: 2026-04-20
+**Status**: Draft
+**Deciders**: pelikhan, Copilot
+
+---
+
+## Part 1 — Narrative (Human-Friendly)
+
+### Context
+
+The gh-aw `compile-all` command discovers workflow sources by listing every `*.md` file (excluding `README.md`) found in `.github/workflows/`. Some repositories legitimately place non-workflow documentation — notes, runbooks, guides — as Markdown files in that same directory. These files have no YAML frontmatter, so the compiler encounters them, fails to parse them, and emits noisy `no frontmatter found` errors. The result is inflated compatibility-failure counts and degraded signal-to-noise for developers running compile-all.
+
+### Decision
+
+We will add a `filterMarkdownFilesWithFrontmatter` step that runs immediately after Markdown file discovery and before any compilation attempt. The filter reads the first line of each candidate file and keeps only those whose first line is exactly `---` — the YAML frontmatter delimiter used by every gh-aw workflow. Files that are empty or whose first line is anything other than `---` are silently skipped. The filter is applied in both `compileAllWorkflowFiles` (in `compile_file_operations.go`) and `compileAllFilesInDirectory` (in `compile_pipeline.go`); the underlying `getMarkdownWorkflowFiles` listing function is left unchanged so that non-compile callers are not affected.
+
+### Alternatives Considered
+
+#### Alternative 1: Suppress the "no frontmatter" error in the parser
+
+The parser could downgrade the `no frontmatter found` diagnostic from an error to a debug-level log, letting compile-all silently continue. This approach avoids the additional I/O of a pre-scan. However, it only masks the symptom: the compiler still attempts a full parse of every non-workflow file, wasting CPU, and the file-discovery boundary between "any Markdown" and "workflow Markdown" remains blurred. It was rejected because it papers over the root cause rather than establishing a clean separation.
+
+#### Alternative 2: Enforce a separate directory for non-workflow docs
+
+Repositories could be required to keep documentation Markdown in a directory other than `.github/workflows/`. This would make the directory semantics unambiguous and eliminate the need for a filter entirely. It was rejected because it is a breaking change for existing repositories that already co-locate docs and workflows, and it imposes a structural constraint on users that has no benefit beyond compile-time convenience.
+
+#### Alternative 3: Name-based convention for workflow files
+
+Workflow Markdown files could be required to follow a specific naming pattern (e.g., end with `-workflow.md`), and compile-all would only process matching files. This would make the filter a simple `filepath.Match` with no I/O. It was rejected because it would require renaming every existing workflow, making it a major backwards-incompatible change.
+
+### Consequences
+
+#### Positive
+- `compile-all` no longer generates false `no frontmatter found` errors for documentation files co-located with workflows.
+- Compatibility-failure counts become more accurate, improving the signal value of compile-all output.
+- The fix is surgically scoped: `getMarkdownWorkflowFiles` and all non-compile callers are untouched.
+
+#### Negative
+- A workflow file whose frontmatter block is accidentally missing or malformed (e.g., starts with a BOM or a blank line before `---`) will be silently skipped rather than producing a clear error, potentially hiding real authoring mistakes.
+- The filter reads file contents for every discovered Markdown file before compilation begins, adding one extra `os.ReadFile` per file over the previous behavior.
+
+#### Neutral
+- The first-line check is intentionally strict (`bytes.Equal(firstLine, []byte("---"))`); any leading whitespace or UTF-8 BOM before `---` will cause the file to be skipped. This is consistent with how YAML frontmatter is defined in the gh-aw spec.
+- Both compile pipelines now share a single filtering function, reducing future drift risk.
+
+---
+
+## Part 2 — Normative Specification (RFC 2119)
+
+> The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this section are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
+### Markdown File Discovery
+
+1. Implementations **MUST** apply the frontmatter filter to the list of Markdown files produced by `getMarkdownWorkflowFiles` before passing any file to the compiler.
+2. Implementations **MUST** retain a Markdown file for compilation if and only if the file's first line (the bytes before the first `\n`) is exactly the three-byte sequence `---`.
+3. Implementations **MUST NOT** pass a Markdown file to the compiler when the file is empty (zero bytes).
+4. Implementations **MUST NOT** pass a Markdown file to the compiler when its first line contains any bytes other than `---` (including leading whitespace or BOM characters).
+5. Implementations **SHOULD** emit a debug-level log entry naming each skipped file so that developers can diagnose unexpected omissions.
+
+### Compile Pipeline Integration
+
+1. Implementations **MUST** apply the frontmatter filter in every code path that calls `getMarkdownWorkflowFiles` and subsequently compiles the resulting files.
+2. Implementations **MUST NOT** modify `getMarkdownWorkflowFiles` to incorporate the filter; the filter **MUST** remain a separate, composable step.
+3. Implementations **MAY** cache file-read results within a single compile-all invocation to avoid reading the same file twice if the filter and the compiler would otherwise both read it.
+
+### Error Handling
+
+1. Implementations **MUST** propagate any `os.ReadFile` error that occurs during filtering as a compile-time error; they **MUST NOT** silently skip a file whose content cannot be read due to an I/O error.
+
+### Conformance
+
+An implementation is considered conformant with this ADR if it satisfies all **MUST** and **MUST NOT** requirements above. Failure to meet any **MUST** or **MUST NOT** requirement constitutes non-conformance.
+
+---
+
+*This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/24679557357) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*

pkg/cli/commands_file_watching_test.go

@@ -15,6 +15,8 @@ import (
 
 	"github.com/github/gh-aw/pkg/testutil"
 	"github.com/github/gh-aw/pkg/workflow"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 // TestWatchAndCompileWorkflows tests the watchAndCompileWorkflows function
@@ -189,6 +191,37 @@ func TestCompileAllWorkflowFiles(t *testing.T) {
 		}
 	})
 
+	t.Run("compile all skips markdown files without frontmatter", func(t *testing.T) {
+		tempDir := testutil.TempDir(t, "test-*")
+		workflowsDir := filepath.Join(tempDir, ".github/workflows")
+		err := os.MkdirAll(workflowsDir, 0o755)
+		require.NoError(t, err)
+
+		validWorkflow := filepath.Join(workflowsDir, "valid.md")
+		validContent := "---\non: push\nengine: claude\n---\n# Valid Workflow\n\nContent"
+		err = os.WriteFile(validWorkflow, []byte(validContent), 0o644)
+		require.NoError(t, err)
+
+		docsFile := filepath.Join(workflowsDir, "docs.md")
+		err = os.WriteFile(docsFile, []byte("# Documentation\n\nNo frontmatter here."), 0o644)
+		require.NoError(t, err)
+
+		compiler := workflow.NewCompiler()
+		stats, err := compileAllWorkflowFiles(compiler, workflowsDir, false)
+		if err != nil {
+			t.Fatalf("compileAllWorkflowFiles failed: %v", err)
+		}
+
+		assert.Equal(t, 1, stats.Total, "Should compile only frontmatter-based markdown workflows")
+		assert.Equal(t, 0, stats.Errors, "Valid workflow should compile without errors")
+
+		validLockFile := filepath.Join(workflowsDir, "valid.lock.yml")
+		assert.FileExists(t, validLockFile, "Expected lock file for valid workflow")
+
+		docsLockFile := filepath.Join(workflowsDir, "docs.lock.yml")
+		assert.NoFileExists(t, docsLockFile, "Should not emit lock file for documentation markdown without frontmatter")
+	})
+
 	t.Run("compile all handles glob error", func(t *testing.T) {
 		// Use a malformed glob pattern that will cause filepath.Glob to error
 		invalidDir := "/tmp/gh-aw/[invalid"

pkg/cli/compile_file_operations.go

@@ -125,10 +125,14 @@ func compileAllWorkflowFiles(compiler *workflow.Compiler, workflowsDir string, v
 	if err != nil {
 		return stats, fmt.Errorf("failed to find markdown files: %w", err)
 	}
+	mdFiles, err = filterMarkdownFilesWithFrontmatter(mdFiles)
+	if err != nil {
+		return stats, fmt.Errorf("failed to filter markdown files: %w", err)
+	}
 	if len(mdFiles) == 0 {
-		compileHelpersLog.Printf("No markdown files found in %s", workflowsDir)
+		compileHelpersLog.Printf("No workflow markdown files found in %s after frontmatter filtering", workflowsDir)
 		if verbose {
-			fmt.Fprintln(os.Stderr, console.FormatInfoMessage("No markdown files found in "+workflowsDir))
+			fmt.Fprintln(os.Stderr, console.FormatInfoMessage("No workflow markdown files found in "+workflowsDir+" (workflow files must start with a frontmatter opener on the first line)"))
 		}
 		return stats, nil
 	}

pkg/cli/compile_pipeline.go

@@ -233,9 +233,13 @@ func compileAllFilesInDirectory(
 	if err != nil {
 		return nil, fmt.Errorf("failed to find markdown files: %w", err)
 	}
+	mdFiles, err = filterMarkdownFilesWithFrontmatter(mdFiles)
+	if err != nil {
+		return nil, fmt.Errorf("failed to filter markdown files: %w", err)
+	}
 
 	if len(mdFiles) == 0 {
-		return nil, fmt.Errorf("no markdown files found in %s", workflowsDir)
+		return nil, fmt.Errorf("no workflow markdown files found in %s (workflow files must start with a frontmatter opener on the first line)", workflowsDir)
 	}
 
 	compileOrchestrationLog.Printf("Found %d markdown files to compile", len(mdFiles))

pkg/cli/workflows.go

@@ -1,9 +1,11 @@
 package cli
 
 import (
+	"bufio"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -288,6 +290,41 @@ func getMarkdownWorkflowFiles(workflowDir string) ([]string, error) {
 	return mdFiles, nil
 }
 
+// filterMarkdownFilesWithFrontmatter keeps only markdown files that begin with frontmatter.
+func filterMarkdownFilesWithFrontmatter(mdFiles []string) ([]string, error) {
+	workflowFiles := make([]string, 0, len(mdFiles))
+	for _, file := range mdFiles {
+		fd, err := os.Open(file)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read workflow file %s: %w", file, err)
+		}
+
+		reader := bufio.NewReader(fd)
+		firstLine, readErr := reader.ReadString('\n')
+		closeErr := fd.Close()
+		if closeErr != nil {
+			return nil, fmt.Errorf("failed to close workflow file %s: %w", file, closeErr)
+		}
+		if readErr != nil && !errors.Is(readErr, io.EOF) {
+			return nil, fmt.Errorf("failed to read workflow file %s: %w", file, readErr)
+		}
+
+		if firstLine == "" {
+			workflowsLog.Printf("Skipping empty markdown file: %s", file)
+			continue
+		}
+
+		if strings.TrimSpace(firstLine) != "---" {
+			workflowsLog.Printf("Skipping markdown file without frontmatter: %s", file)
+			continue
+		}
+
+		workflowFiles = append(workflowFiles, file)
+	}
+
+	return workflowFiles, nil
+}
+
 // fastParseTitle scans markdown content for the first H1 header, skipping an
 // optional frontmatter block, without performing a full YAML parse.
 //

pkg/cli/workflows_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestIsWorkflowFile(t *testing.T) {
@@ -235,3 +236,41 @@ func TestGetMarkdownWorkflowFilesExcludesREADME(t *testing.T) {
 	// Verify total count
 	assert.Len(t, files, 5, "Should have exactly 5 workflow files (excluding README variants)")
 }
+
+func TestFilterMarkdownFilesWithFrontmatter(t *testing.T) {
+	tempDir := t.TempDir()
+	workflowsDir := filepath.Join(tempDir, ".github", "workflows")
+	err := os.MkdirAll(workflowsDir, 0o755)
+	require.NoError(t, err)
+
+	testFiles := map[string]string{
+		"workflow1.md":           "---\non: push\n---\n# Workflow 1",
+		"workflow-crlf.md":       "---\r\non: push\r\n---\r\n# Workflow CRLF",
+		"docs.md":                "# This is documentation",
+		"empty.md":               "",
+		"leading-whitespace.md":  "  ---\non: push\n---\n# Valid Frontmatter Start",
+		"delimiter-not-first.md": "# Header\n---\non: push\n---\n# Not Valid Frontmatter Start",
+	}
+
+	for filename, content := range testFiles {
+		path := filepath.Join(workflowsDir, filename)
+		err := os.WriteFile(path, []byte(content), 0o644)
+		require.NoError(t, err)
+	}
+
+	inputFiles := []string{
+		filepath.Join(workflowsDir, "workflow1.md"),
+		filepath.Join(workflowsDir, "workflow-crlf.md"),
+		filepath.Join(workflowsDir, "docs.md"),
+		filepath.Join(workflowsDir, "empty.md"),
+		filepath.Join(workflowsDir, "leading-whitespace.md"),
+		filepath.Join(workflowsDir, "delimiter-not-first.md"),
+	}
+
+	filtered, err := filterMarkdownFilesWithFrontmatter(inputFiles)
+	require.NoError(t, err)
+	assert.Len(t, filtered, 3)
+	assert.Contains(t, filtered, filepath.Join(workflowsDir, "workflow1.md"))
+	assert.Contains(t, filtered, filepath.Join(workflowsDir, "workflow-crlf.md"))
+	assert.Contains(t, filtered, filepath.Join(workflowsDir, "leading-whitespace.md"))
+}