Clarify foreign fallback scope and env/vars precedence

Author: dgageot

AGENTS.md

@@ -136,8 +136,10 @@ The Go toolchain version comes from `go.mod` (`go 1.26.3`). Tests run with
   wins" so a parent file can override a flattened task by re-declaring it.
   See `loadFlatten` and `TestFlattenedTaskRunsFromRootDir`.
 - **Foreign fallback** (`fallback.go`) — when no `gogo.yaml` is found, gogo
-  walks up looking for a `Taskfile.yml`, `mise.toml`, or `Makefile` whose
-  runner is on `PATH`, and shells out. Order is fixed by `foreignRunners`
+  looks in the current directory only (no walking up — an untrusted
+  checkout's ancestors must never be executed; see
+  `TestFallbackDoesNotWalkUp`) for a `Taskfile.yml`, `mise.toml`, or
+  `Makefile` whose runner is on `PATH`, and shells out. Order is fixed by `foreignRunners`
   and the `make` arm intentionally drops `default` and skips the `--`
   separator (since `make` doesn't understand it). Tests stub the package-
   level `fallbackLookPath` / `fallbackRun` hooks rather than the real exec.
@@ -166,8 +168,10 @@ The Go toolchain version comes from `go.mod` (`go 1.26.3`). Tests run with
   `taskfile.Config` test in `run_test.go` plus a `Parse`-based test in
   `parse_test.go` if YAML shape matters.
 - **Touching env/var resolution**: respect the existing precedence
-  (`BaseEnv` < parent task env < task dotenv < task vars < task env) and the
-  rule that *task dotenv never overrides global dotenv or OS env* (see
+  (`BaseEnv` < parent task env < task dotenv < task env < secrets) and the
+  rule that vars and env are separate namespaces — task `vars:` are NOT
+  exported to the shell environment (see `TestParentVarsDoNotFlowDownAsEnv`) —
+  and the rule that *task dotenv never overrides global dotenv or OS env* (see
   `TestTaskDotenvDoesNotOverrideGlobalDotenv`). Sub-task calls
   (`cmds: - task: X`) propagate the parent's resolved env via
   `Runner.runSubTask` — deps do NOT (they're prerequisites, not sequenced

docs/features/errors/index.md

@@ -14,15 +14,19 @@ You ran gogo from a directory that has no `gogo.yaml` and no ancestor with one e
 
 **Fix:** create a `gogo.yaml` at the project root, or `cd` into a directory that has one above it.
 
-When no `gogo.yaml` is found gogo also looks for foreign task files in the
-same walk:
+When no `gogo.yaml` is found gogo also looks for foreign task files — in the
+**current directory only**, never in ancestors (running gogo inside an
+untrusted checkout must not execute someone else's task file from a parent
+directory):
 
 - `Taskfile.yml` / `taskfile.yml` / `Taskfile.yaml` / `taskfile.yaml` → shells
   out to [`task`](https://taskfile.dev).
 - `mise.toml` → shells out to [`mise run`](https://mise.jdx.dev).
+- `Makefile` / `makefile` / `GNUmakefile` → shells out to `make`.
 
 If the matching binary isn't on `PATH` the runner is silently skipped (so a
-stray Taskfile in a parent directory doesn't break unrelated invocations).
+stray Taskfile doesn't break unrelated invocations when `task` isn't
+installed).
 
 ### `no gogo.yaml found in <dir>`
 

docs/features/variables/index.md

@@ -272,12 +272,15 @@ The environment handed to `/bin/sh` is built up in layers, each one overriding t
 1. **`BaseEnv`** — the OS environment plus global `dotenv:` files
 2. **Inherited parent env** — only on sub-task calls (`cmds: - task: X`); deps don't inherit
 3. **Task `dotenv:`** — never overrides `BaseEnv` (i.e. global dotenv and OS env always win)
-4. **Task `vars:`** — promoted into env so commands can read them with `$NAME`
-5. **Task `env:`** — with cross-references resolved (see [Cross-References Between Env Entries](#cross-references-between-env-entries))
-6. **Task `secrets:`** — **highest precedence**; declaring a secret overrides any same-named placeholder in `env:`
+4. **Task `env:`** — with cross-references resolved (see [Cross-References Between Env Entries](#cross-references-between-env-entries))
+5. **Task `secrets:`** — **highest precedence**; declaring a secret overrides any same-named placeholder in `env:`
+
+Note that task `vars:` are **not** part of this list: vars and env are separate
+namespaces. A `vars:` entry is available to `{{ "{{" }}.VAR}}` templating but is
+never exported to the shell, so `$NAME` in a command only sees the layers above.
 
 A few non-obvious consequences:
 
 - A task `dotenv:` that names a key already set in the global dotenv (or in the user's shell) is silently ignored — see [Dotenv › Resolution Rules](../dotenv/#resolution-rules).
-- Sub-tasks called from `cmds:` see the parent's resolved env (vars + dotenv + `env:` block). Same task name called from two parents with different env runs twice, because gogo bypasses task-level memoization when extra context is in play. See [Parent-to-child Env Propagation](#parent-to-child-env-propagation).
+- Sub-tasks called from `cmds:` see the parent's resolved env (dotenv + `env:` block — not `vars:`). Same task name called from two parents with different env runs twice, because gogo bypasses task-level memoization when extra context is in play. See [Parent-to-child Env Propagation](#parent-to-child-env-propagation).
 - A task that declares both `env: { OPENAI_API_KEY: dummy }` and `secrets: [OPENAI_API_KEY]` gets the secret value at run time. Use this pattern to keep a clear placeholder for local dev while still resolving the real value in CI.