Add top-level flatten: []string to merge YAML files without a namespace

A new `flatten:` field on Config takes a list of YAML file paths whose tasks (and global vars) are merged into the parent file unchanged — colons in task names are preserved as literal characters, not treated as namespace separators. This is the agentic-platform pattern of splitting one logical Taskfile into tasks/*.yml without forcing a namespace prefix on every task name.

Mechanics:

- Paths in `flatten:` resolve relative to the file declaring them; absolute paths and ~ are honored (via resolvePath, same as dotenv).

- A flattened task's `dir:` is resolved against the namespaced ancestor (the root for root flatten, the include's dir for flatten inside a namespaced include), so `dir: backend` written inside tasks/foo.yml means `<root>/backend` — what users naturally expect when splitting one file across many.

- First defined wins on collisions: a parent task or earlier flatten file beats a later one, mirroring how mergeVars already behaves for includes.

- Cycle detection is unified under a single loadStack keyed by absolute file path, so cycles spanning includes and flatten are caught uniformly. The existing "cyclic include" error message and behavior are preserved.

- Flatten works recursively: a flatten file may itself flatten or include further files; included files may themselves declare flatten (their tasks land at that include's namespace).

- Task descriptions extracted from YAML comments still work in flatten files; dotenv files declared inside a flatten file are loaded with the same dedup semantics as includes.

14 new tests cover: basic merge, dir resolution against root, parent-wins and first-flatten-wins collisions, var merging, no-rewrite of local task references at root, comment-derived descs, nested flatten chains, cycle rejection, missing file errors, flatten-inside-include namespacing, absolute paths, raw YAML field parsing, and end-to-end runner execution from the resolved dir.

Assisted-By: docker-agent

Author: dgageot

taskfile/includes.go

@@ -21,13 +21,14 @@ func LoadWithIncludes(dir string) (*Config, error) {
 	return loader.load()
 }
 
-// includeLoader holds shared state while recursively loading included task files.
+// includeLoader holds shared state while recursively loading task files
+// pulled in via `includes:` (namespaced) and `flatten:` (no namespace).
 type includeLoader struct {
-	root         *Config
-	rootDir      string
-	seenDotenv   map[string]struct{} // deduplicates dotenv files across includes
-	dotenvVars   map[string]string   // accumulated dotenv variables
-	includeStack map[string]struct{} // dirs on the current recursion path (cycle detection)
+	root       *Config
+	rootDir    string
+	seenDotenv map[string]struct{} // deduplicates dotenv files across loaded files
+	dotenvVars map[string]string   // accumulated dotenv variables
+	loadStack  map[string]struct{} // absolute file paths currently being loaded (cycle detection)
 }
 
 func newIncludeLoader(root *Config) (*includeLoader, error) {
@@ -38,17 +39,32 @@ func newIncludeLoader(root *Config) (*includeLoader, error) {
 	}
 
 	return &includeLoader{
-		root:         root,
-		rootDir:      root.Dir,
-		seenDotenv:   seenDotenv,
-		dotenvVars:   dotenvVars,
-		includeStack: map[string]struct{}{root.Dir: {}},
+		root:       root,
+		rootDir:    root.Dir,
+		seenDotenv: seenDotenv,
+		dotenvVars: dotenvVars,
+		loadStack:  map[string]struct{}{filepath.Join(root.Dir, fileName): {}},
 	}, nil
 }
 
 func (l *includeLoader) load() (*Config, error) {
 	l.root.Namespaces = make(map[string]string)
 
+	// Process flatten files first (their tasks merge into the root namespace).
+	// Order vs. includes doesn't matter for correctness because both honor
+	// "first defined wins"; the root's own tasks were already loaded at Parse.
+	for _, p := range l.root.Flatten {
+		if err := l.loadFlatten(flattenRequest{
+			parentDir:   l.rootDir,
+			parentFile:  filepath.Join(l.rootDir, fileName),
+			path:        p,
+			namespace:   "",
+			ancestorDir: l.rootDir,
+		}); err != nil {
+			return nil, err
+		}
+	}
+
 	for _, includeName := range l.root.Includes {
 		if err := l.loadInclude(includeRequest{
 			parentDir: l.rootDir,
@@ -77,18 +93,33 @@ func (r includeRequest) childDir() (string, error) {
 	return filepath.Abs(filepath.Join(r.parentDir, r.name))
 }
 
-// loadInclude parses an included task file, loads nested includes, then merges it into the root.
+// loadInclude parses an included task file, loads nested includes and flatten
+// files, then merges it into the root.
 func (l *includeLoader) loadInclude(req includeRequest) error {
 	included, err := l.parseInclude(req)
 	if err != nil {
 		return err
 	}
-	defer l.leaveInclude(included.Dir)
+	defer l.leaveLoad(filepath.Join(included.Dir, fileName))
 
 	if err := l.loadIncludeDotenv(included); err != nil {
 		return err
 	}
 
+	// Process flatten files declared inside this include — their tasks merge
+	// at this include's namespace.
+	for _, p := range included.Flatten {
+		if err := l.loadFlatten(flattenRequest{
+			parentDir:   included.Dir,
+			parentFile:  filepath.Join(included.Dir, fileName),
+			path:        p,
+			namespace:   included.Namespace,
+			ancestorDir: included.Dir,
+		}); err != nil {
+			return err
+		}
+	}
+
 	for _, nested := range nestedIncludes(included) {
 		if err := l.loadInclude(nested); err != nil {
 			return err
@@ -105,14 +136,15 @@ func (l *includeLoader) parseInclude(req includeRequest) (*includedConfig, error
 	if err != nil {
 		return nil, fmt.Errorf("resolving include %q from %s: %w", req.namespace, req.parentFile(), err)
 	}
-	if _, onPath := l.includeStack[childDir]; onPath {
+	expectedFile := filepath.Join(childDir, fileName)
+	if _, onPath := l.loadStack[expectedFile]; onPath {
 		return nil, fmt.Errorf("cyclic include %q detected in %s", req.namespace, req.parentFile())
 	}
-	l.includeStack[childDir] = struct{}{}
+	l.loadStack[expectedFile] = struct{}{}
 
 	child, err := Parse(childDir)
 	if err != nil {
-		delete(l.includeStack, childDir)
+		delete(l.loadStack, expectedFile)
 		return nil, fmt.Errorf("loading include %q from %s: %w", req.namespace, req.parentFile(), err)
 	}
 
@@ -125,8 +157,8 @@ func (l *includeLoader) parseInclude(req includeRequest) (*includedConfig, error
 	return included, nil
 }
 
-func (l *includeLoader) leaveInclude(dir string) {
-	delete(l.includeStack, dir)
+func (l *includeLoader) leaveLoad(filePath string) {
+	delete(l.loadStack, filePath)
 }
 
 func (l *includeLoader) loadIncludeDotenv(included *includedConfig) error {
@@ -161,6 +193,83 @@ func nestedIncludes(parent *includedConfig) []includeRequest {
 	return requests
 }
 
+// flattenRequest describes a single `flatten:` entry pulled from a parent
+// task file. Tasks loaded via flatten merge into the parent's namespace
+// (or the root namespace when invoked from the root) without a prefix.
+type flattenRequest struct {
+	parentDir   string // dir of the file that declared this flatten (path resolution base)
+	parentFile  string // absolute path of that file (for error messages and cycle detection)
+	path        string // the path string written in YAML
+	namespace   string // namespace at which to merge tasks ("" means the root)
+	ancestorDir string // dir of the namespaced ancestor (root, or include dir) for resolving task.Dir
+}
+
+// loadFlatten parses a flatten YAML file, resolves its nested flatten/includes,
+// then merges its tasks into l.root at the given namespace.
+func (l *includeLoader) loadFlatten(req flattenRequest) error {
+	absPath, err := filepath.Abs(resolvePath(req.parentDir, req.path))
+	if err != nil {
+		return fmt.Errorf("resolving flatten %q from %s: %w", req.path, req.parentFile, err)
+	}
+	if _, onPath := l.loadStack[absPath]; onPath {
+		return fmt.Errorf("cyclic flatten %q detected in %s", req.path, req.parentFile)
+	}
+	l.loadStack[absPath] = struct{}{}
+	defer l.leaveLoad(absPath)
+
+	flattenedDir := filepath.Dir(absPath)
+	flattened, err := parseFile(absPath, flattenedDir)
+	if err != nil {
+		return fmt.Errorf("loading flatten %q from %s: %w", req.path, req.parentFile, err)
+	}
+
+	// Load this file's dotenv (paths resolve relative to the file's own dir).
+	childDotenv, err := loadDotenvFiles(flattened.Dir, flattened.Dotenv, l.seenDotenv)
+	if err != nil {
+		return fmt.Errorf("loading dotenv for flatten %q from %s: %w", req.path, req.parentFile, err)
+	}
+	for k, v := range childDotenv {
+		if _, exists := l.dotenvVars[k]; !exists {
+			l.dotenvVars[k] = v
+		}
+	}
+
+	// Recurse: nested flatten files keep the same namespace and ancestor.
+	for _, p := range flattened.Flatten {
+		if err := l.loadFlatten(flattenRequest{
+			parentDir:   flattened.Dir,
+			parentFile:  absPath,
+			path:        p,
+			namespace:   req.namespace,
+			ancestorDir: req.ancestorDir,
+		}); err != nil {
+			return err
+		}
+	}
+
+	// Recurse: nested includes get sub-namespaces under our current one.
+	for _, name := range flattened.Includes {
+		if err := l.loadInclude(includeRequest{
+			parentDir: flattened.Dir,
+			name:      name,
+			namespace: namespaceJoin(req.namespace, name),
+		}); err != nil {
+			return err
+		}
+	}
+
+	l.mergeVars(flattened.Vars)
+	l.mergeFlattenedTasks(flattened, req.namespace, req.ancestorDir)
+	return nil
+}
+
+func namespaceJoin(prefix, name string) string {
+	if prefix == "" {
+		return name
+	}
+	return prefix + ":" + name
+}
+
 // mergeVars merges child global vars into the root. Root vars win conflicts.
 func (l *includeLoader) mergeVars(vars map[string]Var) {
 	if len(vars) == 0 {
@@ -183,6 +292,27 @@ func (l *includeLoader) mergeTasks(included *includedConfig) {
 	}
 }
 
+// mergeFlattenedTasks merges tasks from a flattened file into l.root at the
+// given namespace. With an empty namespace, tasks land in the root unchanged
+// (this is the agentic-platform pattern for splitting one file across many).
+// First defined wins, so a parent file can override a flattened task by
+// declaring it locally with the same name.
+func (l *includeLoader) mergeFlattenedTasks(flattened *Config, namespace, ancestorDir string) {
+	for _, name := range slices.Sorted(maps.Keys(flattened.Tasks)) {
+		finalName := namespaceJoin(namespace, name)
+		if _, exists := l.root.Tasks[finalName]; exists {
+			continue // first wins (root or earlier flatten file beats this one)
+		}
+		task := flattened.Tasks[name]
+		makeTaskDirAbsolute(&task, ancestorDir)
+		if namespace != "" {
+			ic := &includedConfig{Config: flattened, Namespace: namespace}
+			namespaceLocalReferences(&task, ic)
+		}
+		l.root.Tasks[finalName] = task
+	}
+}
+
 func normalizedIncludedTask(included *includedConfig, name string) Task {
 	task := included.Tasks[name]
 	makeTaskDirAbsolute(&task, included.Dir)

taskfile/parse.go

@@ -17,7 +17,13 @@ func Parse(dir string) (*Config, error) {
 	if path == "" {
 		return nil, fmt.Errorf("no gogo.yaml found in %s", dir)
 	}
+	return parseFile(path, dir)
+}
 
+// parseFile reads and parses a YAML file at the given path. The dir argument
+// becomes the Config's Dir, and is used to resolve relative paths for dotenv,
+// nested includes and (for an included gogo.yaml) the task file's own dir.
+func parseFile(path, dir string) (*Config, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return nil, fmt.Errorf("reading %s: %w", path, err)