docs(migration): fix stale no-parity claims for deps/freshness now shipped

#2882 (already merged into this branch) added dependencies.commands/
dependencies.workflows and step-level inputs/artifacts, giving Atmos direct
parity with Task's deps:/sources:/generates: and Make's dependency ordering
and file-timestamp caching. This branch's own migration guides -- the
subject of this PR -- still declared those exact features unsupported
gaps, written before #2882 landed.

- taskfile.mdx / from-taskfile.md: rewrite "parallel-by-default" and
  "sources/generates gap" sections to document dependencies.commands and
  inputs/artifacts as the direct matches, including the automatic dedup
  behavior a hand-built parallel step doesn't provide.
- makefile.mdx / from-makefile.md: document dependencies.commands for
  target chains with a shared prerequisite, and inputs/artifacts (with
  timestamp.changed for make's exact mtime semantics) for file-timestamp
  targets.
- SKILL.md: fix the same false claims in the top-level "Common Problems"
  summary agents read before the per-tool reference files.

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

Author: osterman

agent-skills/skills/atmos-migration/SKILL.md

@@ -101,13 +101,19 @@ These behaviors apply to every task runner. Check them before you open a referen
 
 - **The default order can change.** Task runs `deps:` at the same time by default. Make and Just
   run dependencies one after another, unless the user adds a flag such as `make -j`. Atmos steps
-  always run one after another, unless you put them inside a `parallel` or `matrix` step. Check
-  the source tool's real default. Do not assume the step order stays the same when you move it to
-  Atmos.
-- **Atmos has no file-freshness cache.** Task's `sources:`/`generates:` fields and non-`.PHONY`
-  Make targets both skip work when a file has not changed. Atmos steps always run. The
-  `require`/`assert` step type does not replace this. It only checks that a file exists. It does
-  not check if the file is new. Tell the user this directly.
+  always run one after another, unless you put them inside a `parallel` or `matrix` step. A named
+  task/target/recipe dependency (Task's `deps:`, Make's `target: dep1 dep2`) maps to command-level
+  `dependencies.commands`/`dependencies.workflows`, not to plain steps or a hand-built `parallel`
+  step -- it runs concurrently by default and dedups a dependency shared by more than one caller
+  to a single run, matching Task's/Make's own behavior. Check the source tool's real default. Do
+  not assume the step order stays the same when you move it to Atmos.
+- **Freshness checks map to `inputs`/`artifacts`, not to plain steps.** Task's `sources:`/
+  `generates:` fields and non-`.PHONY` Make targets both skip work when a file has not changed.
+  Atmos's step-level `inputs.sources`/`artifacts.paths` fields are the direct match: with no
+  explicit `when:`, declaring them implicitly means `when: checksum.changed`, and the step is
+  skipped when nothing has changed since its last successful run. This does not carry over on its
+  own -- add `inputs`/`artifacts` to the migrated step yourself. The `require`/`assert` step type
+  does not replace this. It only checks that a file exists, not whether it is fresh.
 - **`workflows.base_path` needs to be set explicitly once the user has their own `atmos.yaml`.**
   A target chain becomes an Atmos workflow (Principle 7), but `atmos workflow <name>` fails with
   `'workflows.base_path' must be configured in 'atmos.yaml'` until you add it (for example,

agent-skills/skills/atmos-migration/references/from-makefile.md

@@ -102,18 +102,19 @@ deploy: build test ## Plan and apply the given ENV (default: dev)
 **Steps:**
 
 1. Turn `ENV ?= dev` into a command `flags:` entry with `default: "dev"`.
-2. Turn the target order (`deploy: build test`) into steps that run in the same order. In this
-    example, the steps call the Shape A commands, one after the other.
-3. Check if the prerequisites are truly independent. In this example, `build` must finish before
-    `test` runs, but nothing else depends on their order relative to each other. When two
-    prerequisites do not depend on each other, use a `parallel` step with `needs:` instead of
-    listing them one after the other. See [Shape C](#shape-c-recursive-or-parallel-make) for the
-    general `parallel`/`matrix` pattern.
-4. Move the Terraform-specific line, `terraform apply -var-file=envs/$(ENV).tfvars`, to
+2. Turn the target list (`deploy: build test`) into command-level `dependencies.commands: [build,
+    test]`. This is the direct match, not a workaround: it resolves through the same DAG scheduler
+    as `parallel`/`matrix` `needs:`, runs concurrently by default -- `make` itself does not
+    guarantee prerequisite order without `-j` either -- and dedups a dependency shared by more
+    than one target to a single run, the same guarantee `make` already gives for free. Do not turn
+    this into plain sequential steps unless one prerequisite genuinely must finish before another
+    starts; if so, declare that dependency directly on the later one's own `dependencies.commands`
+    instead of ordering a flat list.
+3. Move the Terraform-specific line, `terraform apply -var-file=envs/$(ENV).tfvars`, to
     [from-native-terraform.md Shape B](from-native-terraform.md#shape-b-single-dir-with--var-file-from-a-makefile).
     That guide shows how the Terraform side maps to stacks. Here, the line becomes a single
     `type: atmos` step, because `terraform apply` is a native Atmos verb.
-5. Turn `ifeq ($(ENV),prod)` conditionals into a Go template conditional inside a custom command:
+4. Turn `ifeq ($(ENV),prod)` conditionals into a Go template conditional inside a custom command:
     `{{ if eq .Flags.env "prod" }}...{{ end }}`. This is the same pattern used for `--verbose` and
     other boolean flags. Inside a workflow, use `when: !cel 'stack == "prod"'` on the step
     instead.
@@ -126,11 +127,9 @@ commands:
       - name: env
         shorthand: e
         default: "dev"
+    dependencies:
+      commands: [build, test]
     steps:
-      - type: shell
-        command: atmos build
-      - type: shell
-        command: atmos test
       - type: atmos
         command: terraform apply infra -s {{ .Flags.env }}
 ```
@@ -182,10 +181,15 @@ commands:
 
 Atmos steps have no tab requirement. Do not confuse `.PHONY` with a caching feature. If a
 Makefile target is not `.PHONY` and uses file timestamps to skip work when inputs have not
-changed, that caching behavior has no equivalent in Atmos. Atmos steps always run. Tell the user
-this directly. Do not imply that the behavior carries over. Task's `sources:`/`generates:`
-feature has the same problem. See
-[from-taskfile.md](from-taskfile.md#the-sourcesgenerates-gap) for more detail.
+changed, turn it into step `inputs.sources`/`artifacts.paths` -- with no explicit `when:`, that
+implicitly means `when: checksum.changed`, and the step is skipped when nothing has changed since
+its last successful run. It does not carry over automatically; tell the user to add
+`inputs`/`artifacts` to the migrated step themselves. Content hashing (the default) is a
+deliberate upgrade over Make's own mtime comparison -- a fresh `git clone`/CI checkout resets
+every file's mtime, which makes Make think everything changed even when it didn't; use
+`when: timestamp.changed` instead for Make's exact mtime semantics. Task's `sources:`/`generates:`
+feature maps to the same fields. See
+[from-taskfile.md](from-taskfile.md#sourcesgenerates-becomes-inputsartifacts) for more detail.
 
 ### Silent recipes and command echo
 
@@ -210,16 +214,20 @@ language.
 
 ## What Not To Do
 
-- Do not build file-timestamp or `.PHONY` caching as an Atmos feature. It does not exist. State
-  this directly instead of dropping the behavior without comment.
+- Do not confuse `.PHONY` with a caching feature -- it is not one. Do not drop file-timestamp
+  caching without adding the matching `inputs`/`artifacts` fields to the migrated step; it is a
+  direct match, not a gap, but it does not carry over on its own.
+- Do not turn `target: dep1 dep2` into plain sequential steps, or into a hand-built `parallel`
+  step, without first considering command-level `dependencies.commands` -- it runs concurrently
+  by default and dedups a dependency shared by more than one target, the way `make` already does.
 - Do not turn every private or helper target into its own discoverable command by default. If the
   helper is called from only one recipe, put its logic in a step inside the command or workflow
   that needs it. If it needs to be called from more than one recipe, or invoked directly for
   debugging, make it a custom command with `internal: true` instead -- it stays runnable but is
   excluded from `atmos --help` listings and completion suggestions.
 - Do not treat "wrap `atmos` commands in the Makefile" as the final state. It is a valid bridge
-  during early migration, as shown in Shape B, step 4. Leaf targets should become custom
-  commands. Target chains should become workflows.
+  during early migration. Leaf targets should become custom commands. Target chains should become
+  workflows.
 - Do not invent `when:` conditions that check flag values on workflow steps. The `when:` field
   checks CEL context values, such as `stack`, `ci`, and `local`. Flag-based conditionals belong
   in the custom command's own Go templates.

agent-skills/skills/atmos-migration/references/from-taskfile.md

@@ -18,6 +18,11 @@ Terraform-specific steps.
 | `vars:`/`env:` and `sources:`/`generates:`                  | [Shape C](#shape-c-variables-and-up-to-date-checks) |
 | `includes:` (multi-file composition)                        | see [Common Problems](#includes-multi-file-composition) |
 
+`deps:` maps to command-level `dependencies.commands` (concurrent by default, deduped -- the
+direct match). `sources:`/`generates:` maps to step-level `inputs.sources`/`artifacts.paths`
+(implicit `when: checksum.changed` -- the direct match). Neither is a gap; both need the user to
+add the matching field during migration, since neither carries over automatically.
+
 ## Shape A: Simple Tasks
 
 **Before:**
@@ -82,28 +87,19 @@ tasks:
       - terraform -chdir=terraform apply -var-file=envs/dev.tfvars
 ```
 
-This is the most important problem in this migration. Task runs `deps:` at the same time by
-default. Atmos custom-command and workflow steps run one after another by default. This is the
-opposite default. If you turn `deps: [test, lint]` into two plain steps that run one after
-another, the command becomes slower. It also changes what happens when one task fails. To keep
-Task's default behavior, put the dependency tasks inside a `parallel` step:
+Task runs `deps:` at the same time by default. Atmos custom-command and workflow steps run one
+after another by default -- so a `deps:` entry is not a step and never becomes one. It maps to
+the command-level `dependencies.commands` field, which resolves through the same DAG scheduler as
+`parallel`/`matrix` `needs:` and runs concurrently by default -- matching Task's `deps:` behavior
+directly, not working around it with a hand-built `parallel` step:
 
 ```yaml
 commands:
   - name: deploy
     description: Plan and apply the given environment
+    dependencies:
+      commands: [test, lint]
     steps:
-      - name: checks
-        type: parallel
-        fail:
-          mode: wait_all
-        steps:
-          - name: test
-            type: shell
-            command: atmos test
-          - name: lint
-            type: shell
-            command: atmos lint
       - type: atmos
         command: terraform apply infra -s dev
 ```
@@ -113,9 +109,17 @@ task's Terraform code to `components/terraform/infra/` (the default
 `components.terraform.base_path` is `components/terraform`), then swap `infra` for whatever the
 user actually names the component.
 
-If the Taskfile's `deps:` list needs its own internal order, add `needs:` to the steps inside the
-`parallel` block. Do not assume the tasks should run one after another just because that is
-Atmos's default for steps outside a `parallel` or `matrix` block.
+`dependencies.commands` also matches a behavior Task itself has that a hand-rolled `parallel`
+step does not: if two commands both depend on the same one -- for example both `test` and `lint`
+depending on `build` -- Atmos runs `build` exactly once and dedups it, the same as Task's own
+`deps:` graph. A `parallel` step calling `atmos build` from two different places would run it
+twice. If one dependency itself depends on another (`lint` depends on `build`, and `deploy`
+depends on `test` and `lint`), declare that directly on `lint`'s own `dependencies.commands` --
+the scheduler resolves the whole transitive graph itself, still deduping `build` to a single run.
+
+Reach for a `parallel` step instead of `dependencies.commands` only for concurrency inside a
+single command's own steps, not between named commands -- for example, running several shell
+commands side by side that were never their own Task tasks to begin with.
 
 ## Shape C: Variables and Up-to-Date Checks
 
@@ -141,19 +145,33 @@ tasks:
   `default: "dev"`. Task's Sprig `default` filter becomes the plain `default:` field.
 - Turn `env:` into an `env:` map. The two are almost identical.
 
-### The `sources`/`generates` gap
+### `sources:`/`generates:` becomes `inputs`/`artifacts`
 
-Task skips a task's `cmds:` when its `sources:` files match its `generates:` outputs. It checks
-this with a file hash. Atmos steps always run. There is no built-in check for whether a file is
-up to date. The `require`/`assert` step type does not fix this. It only checks that a file, tool,
-or directory exists. It does not compare hashes or timestamps.
+Task skips a task's `cmds:` when its `sources:` files match its `generates:` outputs, checked by
+default with a content hash (Task also supports `method: timestamp` for an mtime-based check).
+The step-level `inputs.sources` and `artifacts.paths` fields are the direct match, with the same
+checksum-by-default/timestamp-as-an-option choice:
 
-If the user depends on `sources:`/`generates:` to skip a slow step, such as code generation, tell
-them plainly that this behavior does not carry over. Then offer two honest choices:
+```yaml
+commands:
+  - name: build
+    description: Compile the deployable artifact
+    steps:
+      - type: shell
+        command: go build -o bin/handler ./cmd/handler
+        inputs:
+          sources: ["cmd/**/*.go"]
+        artifacts:
+          paths: ["bin/handler"]
+```
 
-1. Accept that the step always runs. This is correct for most fast build steps.
-2. Add a hash or timestamp check inside the shell step itself. This is a script the user
-    maintains. It is not a built-in Atmos feature.
+With no explicit `when:`, declaring `inputs`/`artifacts` on a step is enough -- it implicitly
+means `when: checksum.changed`, and the step is skipped when the hash of the matched source files
+matches the hash recorded after the last successful run. This does not carry over on its own --
+add `inputs`/`artifacts` to the migrated step yourself, matching the Taskfile's own
+`sources:`/`generates:` lists. The `require`/`assert` step type is a different, older step type --
+it only checks that a file, tool, or directory exists, not whether it is fresh, so it does not
+replace `inputs`/`artifacts`.
 
 ## Common Problems
 
@@ -173,17 +191,20 @@ Pick the one that fits the content being split:
   "stacks/workflows"`) the first time the user's migration reaches a workflow, or `atmos
   workflow <name>` fails with `'workflows.base_path' must be configured in 'atmos.yaml'`.
 
-### `sources`/`generates` has no built-in match
+### `sources`/`generates` maps to a different field than `steps`
 
-See [Shape C](#the-sourcesgenerates-gap) above. This is the largest real gap in this migration.
-State it directly. Do not gloss over it.
+See [Shape C](#sourcesgenerates-becomes-inputsartifacts) above. It does not carry over
+automatically -- the user must add `inputs`/`artifacts` to the migrated step themselves. State
+that directly. Do not gloss over it, and do not claim it "just works" without the field.
 
 ## What Not To Do
 
-- Do not drop `sources:`/`generates:` caching without comment. State the change directly. Let
-  the user decide how, or whether, to replace it.
-- Do not turn `deps:` into plain sequential steps without warning the user about the change in
-  default concurrency.
+- Do not drop `sources:`/`generates:` without adding the matching `inputs`/`artifacts` fields to
+  the migrated step. It is a direct match, not a gap, but it does not carry over on its own.
+- Do not turn `deps:` into plain sequential steps, or into a hand-built `parallel` step, without
+  first considering command-level `dependencies.commands` -- it is the direct match: concurrent
+  by default, and it dedups a dependency shared by more than one command the same way Task's own
+  `deps:` graph does.
 - Do not describe `require`/`assert` as a freshness or caching check. It only checks that
   something exists.
 - Do not turn every `internal: true` task into its own discoverable command by default. If it is