fix: treat .github/ paths as repo-root-relative in nested bundle manifests (#41790)

Author: Copilot

docs/adr/41790-treat-github-paths-as-repo-root-relative-in-nested-bundles.md

@@ -0,0 +1,44 @@
+# ADR-41790: Treat `.github/` Paths as Repo-Root-Relative in Nested Bundle Manifests
+
+**Date**: 2026-06-26
+**Status**: Draft
+**Deciders**: Unknown (Copilot-authored fix; see PR #41790)
+
+---
+
+### Context
+
+The gh-aw tooling supports "nested bundles" — agentic workflow manifests (`aw.yml`) stored at a sub-path within a repository (e.g., `dependabot/aw.yml`). Bundle manifests can enumerate workflow files under a `files:` key, including paths under `.github/workflows/`. Prior to this fix, the path normalization functions `normalizePackageInstallablePaths` and `scanRepositoryPackageInstallablePaths` unconditionally prepended the bundle's package path to every entry, causing `.github/workflows/foo.md` to resolve to `dependabot/.github/workflows/foo.md` — a path that does not exist, producing HTTP 404 errors at install time. The `.github/` directory is a GitHub-defined repository-root convention; no sub-path equivalent exists.
+
+### Decision
+
+We will treat any path beginning with `.github/` in a bundle manifest as repo-root-relative, bypassing package-prefix logic entirely. All other supported path prefixes (`workflows/`, `agentic-workflows/`) remain relative to the bundle's package root and continue to receive the package-path prefix. This convention is encoded in both `normalizePackageInstallablePaths` (explicit `files:` entries) and `scanRepositoryPackageInstallablePaths` (auto-scan), so the rule applies uniformly regardless of how paths reach the resolver.
+
+### Alternatives Considered
+
+#### Alternative 1: Require manifest authors to always use full repo-root paths
+
+Manifest authors could be required to write `.github/workflows/foo.md` without any special handling — the same path would be expected from both root-level and nested bundles, and the normalization code would be left unchanged. This was rejected because the current normalization logic would silently corrupt any such path by prepending the package directory, and because fixing that would require all existing nested manifests to be audited and updated, with no compiler-enforced guarantee of correctness.
+
+#### Alternative 2: Refactor path representation to store full repo-root paths universally
+
+A deeper alternative would be to change the internal data model so that all collected paths are stored as full repo-root-relative paths from the moment they are collected, removing the dual representation entirely. `isSupportedPackageInstallablePath` would be updated to validate against full paths. This was rejected as out-of-scope for a targeted bug fix: it would require coordinated changes across multiple callers and data structures, and carries a higher risk of introducing regressions in root-bundle behaviour, which is unaffected by the current bug.
+
+### Consequences
+
+#### Positive
+- Nested bundles that reference `.github/workflows/` paths now install correctly without HTTP 404 errors.
+- The convention mirrors the behaviour of GitHub itself — `.github/` is always a repo-root directory — reducing cognitive overhead for manifest authors.
+- Auto-scan for nested bundles now correctly strips the package prefix before validating path support, so previously silently-dropped scan results surface as expected.
+
+#### Negative
+- The path resolution semantics are now context-sensitive: the same path string is interpreted differently depending on its prefix (`.github/` vs everything else). This implicit rule is documented only in code comments, which may not be visible to future manifest authors or contributors unfamiliar with the area.
+- There is no compile-time or schema-level enforcement of the convention; a future refactor of path normalization could inadvertently break the special case if the comments are not noticed.
+
+#### Neutral
+- The fix requires no changes to the `aw.yml` schema or any public-facing API surface; existing valid manifests are unaffected.
+- New tests (`TestResolveWorkflows_NestedRepositoryPackage_GithubWorkflowsPathIsRepoRoot`, `TestResolveWorkflows_NestedRepositoryPackage_AutoScan`) encode the expected behaviour and will catch regressions in both paths.
+
+---
+
+*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*

pkg/cli/add_package_manifest.go

@@ -677,7 +677,15 @@ func scanRepositoryPackageInstallablePaths(owner, repo, packagePath, ref, host s
 		}
 
 		for _, file := range files {
-			if !isSupportedPackageInstallablePath(file) {
+			// listPackageWorkflowFilesForHost returns full repo-root-relative paths
+			// (e.g. "folder/workflows/foo.md" when scanning "folder/workflows/").
+			// isSupportedPackageInstallablePath expects package-relative paths, so
+			// strip the package prefix before validation for nested bundles.
+			pathToValidate := file
+			if packagePath != "" {
+				pathToValidate = strings.TrimPrefix(file, packagePath+"/")
+			}
+			if !isSupportedPackageInstallablePath(pathToValidate) {
 				continue
 			}
 			if _, exists := seen[file]; exists {
@@ -718,7 +726,16 @@ func normalizePackageInstallablePaths(paths []string, packagePath string) []stri
 		if !isSupportedPackageInstallablePath(path) {
 			continue
 		}
-		path = joinRepositoryPackagePath(packagePath, path)
+		// Paths under .github/ are treated as repo-root-relative even in nested
+		// bundles (e.g. a bundle at "dependabot/" with ".github/workflows/foo.md"
+		// refers to the repository-root ".github/workflows/foo.md", not to
+		// "dependabot/.github/workflows/foo.md"). All other paths (e.g. workflows/,
+		// agentic-workflows/) remain relative to the package root.
+		if packagePath != "" && strings.HasPrefix(path, constants.GithubDir) {
+			path = filepath.ToSlash(path)
+		} else {
+			path = joinRepositoryPackagePath(packagePath, path)
+		}
 		if _, exists := seen[path]; exists {
 			continue
 		}

pkg/cli/add_package_manifest_test.go

@@ -559,6 +559,38 @@ files:
 		assert.Equal(t, "packages/repo-assist/README.md", pkg.DocsPath)
 		assert.Equal(t, []string{"packages/repo-assist/workflows/review.md"}, pkg.InstallationSource)
 	})
+
+	t.Run("nested bundle github workflows paths are repo-root-relative", func(t *testing.T) {
+		// When a nested bundle manifest (at "dependabot/aw.yml") lists a
+		// ".github/workflows/" path, it must resolve to the repo-root path
+		// ".github/workflows/foo.md" — NOT to "dependabot/.github/workflows/foo.md".
+		downloadPackageFileFromGitHubForHost = func(owner, repo, path, ref, host string) ([]byte, error) {
+			switch path {
+			case "dependabot/aw.yml":
+				return []byte(`name: Dependabot
+files:
+  - workflows/review.md
+  - .github/workflows/dependabot-orchestrator.md
+`), nil
+			case "dependabot/README.md":
+				return []byte("# Dependabot\n"), nil
+			default:
+				return nil, createRepositoryPackageNotFoundError(path)
+			}
+		}
+		listPackageWorkflowFilesForHost = func(owner, repo, ref, workflowPath, host string) ([]string, error) {
+			t.Fatalf("unexpected scan of %s", workflowPath)
+			return nil, nil
+		}
+
+		pkg, err := resolveRepositoryPackage(&RepoSpec{RepoSlug: "owner/repo", PackagePath: "dependabot"}, "")
+		require.NoError(t, err)
+		// workflows/ path is package-relative; .github/workflows/ is repo-root-relative.
+		assert.Equal(t, []string{
+			"dependabot/workflows/review.md",
+			".github/workflows/dependabot-orchestrator.md",
+		}, pkg.InstallationSource)
+	})
 }
 
 func TestResolveWorkflows_RepositoryPackage(t *testing.T) {
@@ -729,6 +761,128 @@ files:
 	assert.Equal(t, "folder/workflows/review.md", resolved.Workflows[0].Spec.WorkflowPath)
 }
 
+// TestResolveWorkflows_NestedRepositoryPackage_GithubWorkflowsPathIsRepoRoot reproduces
+// the bug reported in gh-aw#41789: a ".github/workflows/" path listed in the manifest of
+// a nested bundle (e.g. "dependabot/aw.yml") must resolve to the repository-root path
+// ".github/workflows/foo.md", not to "dependabot/.github/workflows/foo.md".
+func TestResolveWorkflows_NestedRepositoryPackage_GithubWorkflowsPathIsRepoRoot(t *testing.T) {
+	originalFetchFn := fetchWorkflowFromSourceWithContextFn
+	originalDownload := downloadPackageFileFromGitHubForHost
+	originalList := listPackageWorkflowFilesForHost
+	originalDirFiles := listPackageDirFilesForHost
+	originalDirSubdirs := listPackageDirSubdirsForHost
+	originalDefaultBranch := getRepositoryPackageDefaultBranch
+	t.Cleanup(func() {
+		fetchWorkflowFromSourceWithContextFn = originalFetchFn
+		downloadPackageFileFromGitHubForHost = originalDownload
+		listPackageWorkflowFilesForHost = originalList
+		listPackageDirFilesForHost = originalDirFiles
+		listPackageDirSubdirsForHost = originalDirSubdirs
+		getRepositoryPackageDefaultBranch = originalDefaultBranch
+	})
+	getRepositoryPackageDefaultBranch = func(repoSlug, host string) (string, error) {
+		return "main", nil
+	}
+	listPackageDirFilesForHost = func(owner, repo, ref, dirPath, host string) ([]string, error) {
+		return nil, createRepositoryPackageNotFoundError(dirPath)
+	}
+	listPackageDirSubdirsForHost = func(owner, repo, ref, dirPath, host string) ([]string, error) {
+		return nil, createRepositoryPackageNotFoundError(dirPath)
+	}
+
+	downloadPackageFileFromGitHubForHost = func(owner, repo, path, ref, host string) ([]byte, error) {
+		switch path {
+		case "dependabot/aw.yml":
+			return []byte(`name: Dependabot Workflows
+files:
+  - .github/workflows/dependabot-orchestrator.md
+`), nil
+		case "dependabot/README.md":
+			return []byte("# Dependabot Workflows\n"), nil
+		}
+		return nil, createRepositoryPackageNotFoundError(path)
+	}
+	listPackageWorkflowFilesForHost = func(owner, repo, ref, workflowPath, host string) ([]string, error) {
+		t.Fatalf("unexpected scan of %s", workflowPath)
+		return nil, nil
+	}
+	fetchWorkflowFromSourceWithContextFn = func(_ context.Context, spec *WorkflowSpec, _ bool) (*FetchedWorkflow, error) {
+		return &FetchedWorkflow{
+			Content:    []byte("---\nname: Dependabot Orchestrator\non: push\n---\n"),
+			CommitSHA:  "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+			IsLocal:    false,
+			SourcePath: spec.WorkflowPath,
+		}, nil
+	}
+
+	resolved, err := ResolveWorkflows(context.Background(), []string{"owner/repo/dependabot"}, false)
+	require.NoError(t, err)
+	require.Len(t, resolved.Workflows, 1)
+	// Must be the repo-root path, NOT "dependabot/.github/workflows/dependabot-orchestrator.md".
+	assert.Equal(t, ".github/workflows/dependabot-orchestrator.md", resolved.Workflows[0].Spec.WorkflowPath)
+}
+
+// TestResolveWorkflows_NestedRepositoryPackage_AutoScan tests that auto-scan (no explicit
+// files: in the manifest) finds workflows inside a nested bundle's own directories.
+func TestResolveWorkflows_NestedRepositoryPackage_AutoScan(t *testing.T) {
+	originalFetchFn := fetchWorkflowFromSourceWithContextFn
+	originalDownload := downloadPackageFileFromGitHubForHost
+	originalList := listPackageWorkflowFilesForHost
+	originalDirFiles := listPackageDirFilesForHost
+	originalDirSubdirs := listPackageDirSubdirsForHost
+	originalDefaultBranch := getRepositoryPackageDefaultBranch
+	t.Cleanup(func() {
+		fetchWorkflowFromSourceWithContextFn = originalFetchFn
+		downloadPackageFileFromGitHubForHost = originalDownload
+		listPackageWorkflowFilesForHost = originalList
+		listPackageDirFilesForHost = originalDirFiles
+		listPackageDirSubdirsForHost = originalDirSubdirs
+		getRepositoryPackageDefaultBranch = originalDefaultBranch
+	})
+	getRepositoryPackageDefaultBranch = func(repoSlug, host string) (string, error) {
+		return "main", nil
+	}
+	listPackageDirFilesForHost = func(owner, repo, ref, dirPath, host string) ([]string, error) {
+		return nil, createRepositoryPackageNotFoundError(dirPath)
+	}
+	listPackageDirSubdirsForHost = func(owner, repo, ref, dirPath, host string) ([]string, error) {
+		return nil, createRepositoryPackageNotFoundError(dirPath)
+	}
+
+	downloadPackageFileFromGitHubForHost = func(owner, repo, path, ref, host string) ([]byte, error) {
+		switch path {
+		case "mypkg/aw.yml":
+			return []byte("name: My Package\n"), nil
+		case "mypkg/README.md":
+			return []byte("# My Package\n"), nil
+		}
+		return nil, createRepositoryPackageNotFoundError(path)
+	}
+	// Auto-scan returns full repo-root-relative paths, as the GitHub API does.
+	listPackageWorkflowFilesForHost = func(owner, repo, ref, workflowPath, host string) ([]string, error) {
+		switch workflowPath {
+		case "mypkg/workflows":
+			return []string{"mypkg/workflows/pr-review.md"}, nil
+		default:
+			return nil, createRepositoryPackageNotFoundError(workflowPath)
+		}
+	}
+	fetchWorkflowFromSourceWithContextFn = func(_ context.Context, spec *WorkflowSpec, _ bool) (*FetchedWorkflow, error) {
+		return &FetchedWorkflow{
+			Content:    []byte("---\nname: PR Review\non: push\n---\n"),
+			CommitSHA:  "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+			IsLocal:    false,
+			SourcePath: spec.WorkflowPath,
+		}, nil
+	}
+
+	resolved, err := ResolveWorkflows(context.Background(), []string{"owner/repo/mypkg"}, false)
+	require.NoError(t, err)
+	require.Len(t, resolved.Workflows, 1)
+	// Auto-scanned path must be the full repo-root path returned by the API.
+	assert.Equal(t, "mypkg/workflows/pr-review.md", resolved.Workflows[0].Spec.WorkflowPath)
+}
+
 func TestResolveWorkflows_FallsBackToWorkflowWhenNestedManifestMissing(t *testing.T) {
 	originalFetchFn := fetchWorkflowFromSourceWithContextFn
 	originalDownload := downloadPackageFileFromGitHubForHost