asgard 0.3.0 → 0.3.2

data/docs/api.md

@@ -11,7 +11,7 @@ These class methods are defined on the `Asgard` module itself.
 | Method | Signature | Description |
 |---|---|---|
 | `run!` | `Asgard.run!(argv)` | Main entry point. Finds `.loki`, loads all task files, validates the dependency graph, and dispatches via Thor. Handles its own errors: missing `.loki` and circular dependencies both produce a clean one-line message and `exit 1`. |
-| `find_task_file` | `Asgard.find_task_file → String, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns the absolute path string of the first match, or `nil` if none is found. |
+| `find_task_file` | `Asgard.find_task_file → Pathname, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns a `Pathname` of the first match, or `nil` if none is found. |
 
 ### `run!` Details
 
@@ -35,7 +35,7 @@ These methods are defined as `module_function` on `Kernel` and are therefore ava
 
 | Method | Signature | Returns | Description |
 |---|---|---|---|
-| `loki_up` | `loki_up(name = ".loki") → String, nil` | Absolute path or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns the first match's absolute path, or `nil` if not found. Exact filenames only — does not expand globs. |
+| `loki_up` | `loki_up(name = ".loki") → Pathname, nil` | `Pathname` or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns a `Pathname` for the first match, or `nil` if not found. Exact filenames only — does not expand globs. |
 | `import` | `import(path) → true, false` | `true` if any file newly loaded | Loads one `.loki` file or a glob of `.loki` files. Relative paths resolve relative to the caller's file (like `require_relative`). Idempotent via `$LOADED_FEATURES`. Raises `ArgumentError` if `path` does not end with `.loki`. Raises `LoadError` if a non-glob path does not exist. |
 | `import_up` | `import_up(name = ".loki") → true, false` | `true` if any file newly loaded | Combines `loki_up` and `import`. Walks ancestors to find the file or glob match, then loads it. Returns `false` if nothing is found. |
 | `debug?` | `debug? → true, false` | `$DEBUG` | Returns the current value of `$DEBUG`. Set to `true` by `--debug` on the CLI or directly via `$DEBUG = true`. |
@@ -53,11 +53,11 @@ loki_up(".env")               # find the nearest .env file up the tree
 loki_up("VERSION")            # find a VERSION file in CWD or any ancestor
 ```
 
-Returns an absolute path string or `nil`. Does not load the file.
+Returns a `Pathname` or `nil`. Does not load the file. `Pathname` is accepted by `import`, `dotenv`, `load`, and standard Ruby file methods — no `.to_s` conversion needed in common usage.
 
 ```ruby
 if (path = loki_up("gem_tasks.loki"))
-  import path
+  import path          # Pathname accepted directly
 end
 
 # Pass the located .env to dotenv — works from any subdirectory
@@ -111,13 +111,62 @@ import_up "*.loki"                 # find the nearest ancestor with *.loki files
 
 | Method | Signature | Description |
 |---|---|---|
-| `depends_on` | `depends_on(*tasks)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. |
+| `depends_on` | `depends_on(*tasks)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. A sole `Proc`/lambda defers resolution to `validate_deps!` (after every `.loki` file has loaded) instead of resolving immediately — see [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form). |
 | `dotenv` | `dotenv(path = ".env")` | Load the specified `.env` file into `ENV` using the dotenv gem. Silently skipped if the file does not exist. Called at class-load time. |
+| `header` | `header(text)` | Append a line of text shown above the commands list in `asgard help`. Each call adds another line. No-op for per-command help. |
+| `footer` | `footer(text)` | Prepend a line of text shown below the options block in `asgard help`. Each call inserts above the previous lines. No-op for per-command help. |
+| `no_negate` | `no_negate(*names)` | Suppress `[--no-name]` / `[--skip-name]` help entries for one or more boolean class options. Call after the `class_option` declaration. |
 | `sh` | `sh(script, silent: false)` | Instance method. Run a shell command or multiline heredoc. Single-line → `system(script)`; multiline → `system("bash", "-c", script)`. Exits with the command's status on failure. |
 | `shebang` | `shebang(interpreter, script, silent: false)` | Instance method. Write `script` to a tempfile and execute it with `interpreter`. See the [Shell Helpers](shell.md) page for the full interpreter table. |
-| `validate_deps!` | `Tasks.validate_deps!` | Build and topologically sort the full dependency graph using Dagwood. Raises `Asgard::CircularDependencyError` on cycles. Called by `run!` at startup. |
+| `validate_deps!` | `Tasks.validate_deps!` | Build and topologically sort the full dependency graph using stdlib `TSort`. Raises `Asgard::CircularDependencyError` on cycles. Called by `run!` at startup. |
 | `_reset_ran!` | `Tasks._reset_ran!` | Clear the per-invocation task deduplication set. Called by `run!` before dispatching. Thread-safe via Mutex. |
 
+### `header` and `footer` Accumulation
+
+Both `header` and `footer` accumulate across multiple calls and across multiple imported `.loki` files, but they accumulate in opposite directions by design.
+
+**`header` appends** — each call adds to the bottom of the header block:
+
+```ruby
+# .loki
+import "quality.loki"
+import "gem_tasks.loki"
+
+class Tasks
+  header "Project: myapp"       # line 1
+  header "Root: #{loki_up.parent}"  # line 2
+end
+```
+
+Result in `asgard help`:
+```
+Project: myapp
+Root: /home/user/myapp
+```
+
+**`footer` prepends** — each call inserts at the top of the footer block:
+
+```ruby
+class Tasks
+  footer "Github: https://github.com/org/myapp"  # ends up second
+  footer "Docs: https://myapp.example.com"        # ends up first
+end
+```
+
+Result in `asgard help`:
+```
+Docs: https://myapp.example.com
+Github: https://github.com/org/myapp
+```
+
+**Why the asymmetry?** When task files are split across multiple `.loki` files, the base `.loki` is loaded first and any imported files are loaded after. With `header`, earlier-loaded content appears first (the project banner stays at the top). With `footer`, later-loaded content appears first — this allows an imported file to inject a note that appears above the base footer rather than after it.
+
+In practice: if only one file calls `header` and one file calls `footer`, the direction doesn't matter. The difference is visible only when multiple `.loki` files both call `header` or both call `footer`.
+
+Neither `header` nor `footer` appears when running per-command help (`asgard help <task>`).
+
+---
+
 ### `depends_on` Argument Shapes
 
 ```ruby
@@ -125,8 +174,14 @@ depends_on :build                          # single sequential dep
 depends_on :clean, :build                  # two sequential deps
 depends_on [:lint, :typecheck]             # lint and typecheck run in parallel
 depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently, then test
+
+# A sole Proc/lambda defers resolution to validate_deps!, after every .loki
+# file has loaded — must return the same shape the splat form above would.
+depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
 ```
 
+See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form) for the full explanation of the Proc form — why it exists, when it runs, and how errors are reported.
+
 ---
 
 ## `Tasks` Built-ins
@@ -137,12 +192,79 @@ depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently
 |---|---|---|
 | `class_option :debug` | class option | `--debug` flag. Sets `$DEBUG = true` before any task runs. Boolean, default `false`. |
 | `class_option :verbose` | class option | `--verbose` flag. Sets `$VERBOSE = true` before any task runs. Boolean, default `false`. |
-| `_version` | private task method | Implements `--version`. Prints `Asgard::VERSION` and exits. Registered via `map "--version" => :_version`. Uses `_` prefix convention. |
+| `class_option :version` | class option | `--version` flag. Handled by `Asgard.run!` before the `.loki` file is loaded — prints `Asgard::VERSION` and exits. `no_negate :version` suppresses the `[--no-version]` / `[--skip-version]` help entries. |
+| `class_option :doctor` | class option | `--doctor` flag. Handled by `Asgard.run!` before the `.loki` file is loaded — runs `Asgard::Doctor.new.run` and exits. `no_negate :doctor` suppresses the `[--no-doctor]` / `[--skip-doctor]` help entries. |
 | `debug?` | Kernel module function | Returns `$DEBUG`. Available everywhere via `Kernel`. |
 | `verbose?` | Kernel module function | Returns `$VERBOSE`. Available everywhere via `Kernel`. |
 
 ---
 
+## `Asgard::Doctor`
+
+`asgard --doctor` diagnoses `.loki` resolution, import chains, and task definitions for the current directory. It deliberately bypasses the normal `Tasks` boot sequence used by `run!`, so it can still report findings in situations that would otherwise abort the whole process — a broken `.loki` file, a circular or undefined dependency, or a task silently redefined by a later `def`.
+
+| Method | Signature | Description |
+|---|---|---|
+| `new` | `Asgard::Doctor.new(dir = Dir.pwd)` | Builds a doctor scoped to `dir`. |
+| `run` | `doctor.run` | Runs the full diagnostic pass and prints a report to stdout. Does not raise or exit — callers (like `Asgard.run!`) decide what to do afterward. |
+| `ancestor_markers` | `Asgard::Doctor.ancestor_markers(dir) → Array<String>` | Every `.loki` marker from `dir` up to the filesystem root, nearest first. Unlike `loki_up`, it collects every match instead of stopping at the first, so shadowed ancestor markers can be reported. |
+| `duplicate_methods` | `Asgard::Doctor.duplicate_methods(method_log) → Hash` | Given an `Asgard::Base` subclass's `_method_log`, returns the subset of entries defined at more than one location — same file or different — which is exactly what a silent `def` override looks like. |
+
+Findings fall into three levels: `:info` (what was found — the marker used, each import's result), `:warn` (shadowed markers that are never reached), and `:error` (load failures, redefined methods, dependency graph problems).
+
+After the findings, the report prints a **Tasks by file** section: every Thor command, grouped by the `.loki` file it's defined in, as `relative/path:line` — a format an editor can jump straight to. A task name defined at more than one location gets every definition annotated inline: the earlier one(s) are marked `OVERRIDDEN by <file>:<line> — never callable`, and the winning (last) definition is marked `active — redefines <file>:<line>`. This is the exact class of bug the flag was built to catch — a later `def` silently replacing an earlier one, with no error anywhere else in the toolchain. The report ends with a one-line summary and a count of problems/warnings, where each overridden task counts as one problem.
+
+```bash
+asgard --doctor
+```
+
+The asgard repo ships its own live example of this: `xyzzy.loki` defines a `xyzzy` task, and the top-level `.loki` (which imports it) reopens `Tasks` and defines `xyzzy` again — so the one from `xyzzy.loki` is silently dead. Clone the repo and run `asgard --doctor` from its root to see this for yourself:
+
+```
+asgard doctor -- /path/to/asgard
+============================================================
+  [INFO] using .loki marker: /path/to/asgard/.loki
+  [INFO] import "quality.loki" -> /path/to/asgard/quality.loki
+  [INFO] import "gem_tasks.loki" -> /path/to/asgard/gem_tasks.loki
+  [INFO] import "git.loki" -> /path/to/asgard/git.loki
+  [INFO] import "xyzzy.loki" -> /path/to/asgard/xyzzy.loki
+
+Tasks by file:
+
+  .loki
+    xyzzy  .loki:15   active — redefines xyzzy.loki:6
+
+  quality.loki
+    test          quality.loki:6
+    test_verbose  quality.loki:15
+    quality       quality.loki:21
+    rubocop       quality.loki:34
+    rubocop_fix   quality.loki:43
+    flog_check    quality.loki:48
+    flay_check    quality.loki:82
+    reek          quality.loki:104
+
+  gem_tasks.loki
+    console  gem_tasks.loki:6
+    build    gem_tasks.loki:16
+    install  gem_tasks.loki:24
+    release  gem_tasks.loki:31
+
+  git.loki
+    push   git.loki:6
+    pull   git.loki:9
+    fetch  git.loki:12
+
+  xyzzy.loki
+    xyzzy  xyzzy.loki:6   OVERRIDDEN by .loki:15 — never callable
+============================================================
+1 problem(s), 1 warning(s).
+```
+
+The warning is a shadowed ancestor `.loki` marker one directory further up the tree — unrelated to the override, and something you may or may not see depending on what's above the repo on your own machine.
+
+---
+
 ## `Asgard::Base` Internal Class Methods
 
 These are implementation details exposed for extensibility. Prefer the DSL methods above in normal use.
@@ -154,7 +276,6 @@ These are implementation details exposed for extensibility. Prefer the DSL metho
 | `_running` | `Set` of task name symbols currently executing (started but not yet finished). |
 | `_cond` | Hash of `ConditionVariable` objects keyed by task name; threads wait here when a dep is in-flight. |
 | `_ran_mutex` | `Mutex` protecting `_done`, `_running`, and `_cond` for thread-safe access. |
-| `_build_dep_graph(stages)` | Translates the stage array (from `_deps`) into a Dagwood-compatible hash. |
 
 ---
 
@@ -164,7 +285,7 @@ These are implementation details exposed for extensibility. Prefer the DSL metho
 
 1. Sets `$DEBUG` / `$VERBOSE` from `options` if the corresponding flags are present.
 2. Tries to acquire a run token (`acquire_run_token`): if the task is already in `_done`, returns immediately (skip); if it is in `_running`, waits on the `_cond` ConditionVariable until it finishes, then returns (skip); otherwise adds the task to `_running` and continues.
-3. Resolves dependency stages from `_deps`, builds the Dagwood graph, and executes groups (parallel groups in threads, sequential groups one at a time).
+3. Resolves dependency stages from `_deps` — already the parallel-group execution plan `depends_on` built — and executes each group in order (parallel groups in threads, sequential groups one at a time).
 4. Calls `command.run(self, *args)` to execute the task itself.
 5. In an `ensure` block, adds the task to `_done` and broadcasts on its `_cond` to wake any waiting threads.
 
@@ -194,7 +315,6 @@ end
 | Gem | Version | Purpose |
 |---|---|---|
 | [thor](https://github.com/rails/thor) | `~> 1.0` | CLI framework; provides the full task DSL |
-| [dagwood](https://rubygems.org/gems/dagwood) | `~> 1.0` | DAG library for dependency graph resolution and topological sort |
 | [dotenv](https://github.com/bkeepers/dotenv) | `~> 3.0` | `.env` file loading |
 
 ---

data/docs/changelog.md

@@ -8,8 +8,36 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asg
 
 ## [Unreleased]
 
+### Added
+
+- **`--doctor` built-in CLI flag** — diagnoses `.loki` resolution, import chains, and task definitions for the current directory. Handled directly in `Asgard.run!` (same pattern as `--version`), so it works even when a broken file, a circular/undefined dependency, or a silently redefined task would otherwise abort the whole process. Backed by the new `Asgard::Doctor` class. Includes a "Tasks by file" listing — every command grouped by the file it's defined in, as `file:line`, with any silently-overridden task annotated inline (`OVERRIDDEN by ...` / `active — redefines ...`). See [API Reference](api.md#asgarddoctor).
+- **`helper` DSL method** — defines a method available in both class context (e.g. inside `header`) and instance context (inside task methods) with a single declaration. Eliminates the manual `def self.name` + `no_commands { private def name = self.class.name }` boilerplate. Supports positional arguments, keyword arguments, and block arguments. See [Helper Methods](helpers.md).
+- **Flay and Reek quality gates** — `flay_check` checks for structural duplication (mass ≥ 150); `reek` checks code smells. Reviewed findings are grandfathered precisely, per method and detector, via `reek --todo`-generated `exclude:` entries in `.reek.yml` — a genuinely new smell still fails the gate even at an already-reviewed method.
+- **`test_verbose`, `console` tasks** — verbose test output and an IRB console with the gem loaded.
+- **`git.loki`** — per-repo `push`/`pull`/`fetch` tasks.
+- **`typos_check` / `typos_fix` tasks** — spell-checking via the external `typos` CLI (`brew install typos-cli`). Reports `SKIP` (not a failure) if `typos` isn't installed, with a one-line install hint.
+- **`fasterer_check` task** — performance-idiom suggestions from the `fasterer` gem, reported as `WARN` (non-blocking).
+- **`SKIP` / `WARN` quality-gate statuses** — alongside `PASS`/`FAIL`; only `FAIL` blocks `quality`.
+- Every quality gate now writes full detail to a `<gate>_output.txt` file (gitignored) and prints just a one-line summary to stdout.
+- **`asgard tree`** now shows the project header/footer, matching `asgard help`.
+- **`bundler_audit_check` task** — `bundle-audit check --update` against `Gemfile.lock`; `FAIL` on any known vulnerability.
+- **`quality_rails.loki`** — imported only when `Rails` is defined; ships `brakeman_check` as a Rails security-scan example. No wiring needed — `quality` discovers it automatically (see `depends_on` below).
+- **`depends_on` accepts a Proc/lambda**, not just a fixed list — resolved once, in `validate_deps!`, after every `.loki` file has loaded, instead of immediately. Solves "load order matters" for a dependency list that can't be known upfront, e.g. every task ending in `_check` across several files. See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form).
+
+### Changed
+
+- **`quality` task** — discovers every `*_check` task at run time (via a `depends_on` Proc) rather than a fixed list, and runs them all in parallel with a colorized PASS/FAIL/WARN/SKIP summary and tally.
+- **`test`, `rubocop`, `reek` renamed to `test_check`, `rubocop_check`, `reek_check`** — consistency with the other gates is what makes `quality`'s automatic discovery possible.
+- **`release` task** — prompts for confirmation unless `-y`/`--yes` is passed.
+- **`Asgard::Base` and `Asgard::Doctor` split into mixins** — `lib/asgard/base/{registry,dependency_graph,task_dsl,dispatch}.rb` and `lib/asgard/doctor/{task_sections,report}.rb`. No behavior change; drops both classes' Reek `TooManyMethods`/`TooManyInstanceVariables` warnings to zero.
+
+### Fixed
+
+- **`bin/asgard`** — switched from `require "asgard"` to `require_relative "../lib/asgard"` so the executable always loads the library shipped alongside it, instead of whatever `asgard` gem happens to be installed separately.
+
 ### Removed
 
+- **`reek_baseline` / `ensure_quality_dir` tasks and `.quality/`** — superseded by precise per-method `exclude:` entries in `.reek.yml` (see the Reek gate entry above).
 - **`var` DSL method** — replaced by native Ruby class variables. Use `@@name ||= "value".freeze` in the class body. Class variables are visible in all task instance methods and in subcommand subclasses, making them the correct tool for shared configuration in a Thor-based task runner. See [Variables](variables.md).
 
 ## [0.2.0] — 2026-05-29

data/docs/dependencies.md

@@ -145,9 +145,54 @@ When `asgard ci` runs, `setup` executes once even though both `test` and `lint`
 
 ---
 
+## Transitive Dependencies
+
+When a dependency has its own dependencies, Asgard resolves them recursively before running the dependent task. The deduplication set ensures each task runs at most once regardless of how many paths lead to it.
+
+Consider this graph:
+
+```ruby
+class Tasks
+  desc "Fetch gems"
+  def setup = sh "bundle install"
+
+  depends_on :setup
+  desc "Compile assets"
+  def build = sh "rake assets:precompile"
+
+  desc "Check code style"
+  def lint = sh "bundle exec rubocop"
+
+  depends_on :build, :lint, :setup
+  desc "Run the full pipeline"
+  def ci = puts "Done."
+end
+```
+
+`ci` declares three sequential dependencies: `build`, `lint`, `setup`. But `build` itself depends on `setup`. The effective execution order is:
+
+```
+setup          ← run as build's prerequisite
+  ↓
+build
+  ↓
+lint
+  ↓
+(setup skipped — already done)
+  ↓
+ci
+```
+
+`setup` runs once — on its first encounter as `build`'s prerequisite. When `ci`'s own stage for `setup` is reached, the deduplication set skips it.
+
+!!! tip
+    When a task is both a transitive dependency and a direct dependency, declare it only where it logically belongs — as a prerequisite of the task that needs it. Declaring it redundantly at the top level is harmless (deduplication handles it) but adds noise.
+
+---
+
 ## Circular Dependency Detection
 
-Asgard validates the full dependency graph using [Dagwood](https://rubygems.org/gems/dagwood) before any task runs. A circular dependency produces a clean error and exits:
+Asgard validates the full dependency graph using stdlib [TSort](https://docs.ruby-lang.org/en/master/TSort.html) before any task runs. A circular dependency produces a clean error and exits:
 
 ```ruby
 class Tasks
@@ -187,7 +232,43 @@ class Tasks
 end
 ```
 
-When `--auto-load` is used, `*.loki` files are loaded alphabetically, so `build.loki` loads before `test.loki`. If you need to control load order, use explicit `require_relative` from `.loki`.
+Because `*.loki` files are loaded alphabetically when `import "*.loki"` is used, `build.loki` loads before `test.loki`. If you need to control load order precisely, use explicit `import` calls with full filenames rather than a glob.
+
+---
+
+## Dynamic Dependencies (Proc Form)
+
+`depends_on` normally takes a fixed list, recorded the moment the `def` right after it is encountered — which is why load order matters, as above. Pass a `Proc` or lambda instead, and that list is computed *later*, after every `.loki` file has finished loading, rather than at the point `depends_on` itself is evaluated:
+
+```ruby
+depends_on -> { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+desc "Run every *_check quality gate task in parallel"
+def quality
+  # ...
+end
+```
+
+This solves exactly the "load order matters" problem from the previous section: a plain array can only name tasks that already exist in `.loki` files loaded *before* this one. A Proc is resolved once every file has loaded, so it can safely reference a task defined in a file that hasn't been imported yet at the point `depends_on` is written — including one that only exists conditionally, e.g. a Rails-specific task file imported with `import "quality_rails.loki" if defined?(Rails)`.
+
+**Shape:** the Proc must return exactly what the plain-array form would receive as its splat arguments — an array of stages, each a `Symbol` (sequential) or `Array` (parallel group). The example above returns `[[:a_check, :b_check, :c_check]]`: one stage, containing every matching task, all running in parallel — the same shape as `depends_on [:a_check, :b_check, :c_check]`.
+
+**When it runs:** once, when `validate_deps!` runs (right after the `.loki` chain finishes loading, before any task dispatches). The resolved result replaces the Proc in the dependency table, so cycle detection, undefined-task checks, and arity checks all run against the *resolved* list — a Proc that references an undefined task, or that itself introduces a cycle, is caught at startup exactly like a plain array would be:
+
+```bash
+asgard quality
+# asgard: undefined task(s) in depends_on: ghost_check
+```
+
+**`self` inside the Proc:** since the Proc is written directly in a `class Tasks` body, it lexically captures that class as `self` — so it can call `all_commands`, `_deps`, or any other class-level method bare, without a `self.class.` prefix, even though it's actually invoked later from inside `validate_deps!`.
+
+**If the Proc raises**, the error is caught and re-raised as `Asgard::Error` naming the task it was declared for:
+
+```
+asgard: depends_on proc for 'quality' raised RuntimeError: boom
+```
+
+!!! tip
+    Reach for this only when the dependency list genuinely can't be known until every file has loaded — like "every task whose name ends in `_check`," discovered across several `.loki` files. For a fixed, known-upfront list, the plain array form is simpler and reads just as clearly.
 
 ---
 

data/docs/getting-started.md

@@ -138,24 +138,26 @@ myproject/
   qa.loki        ← test and lint tasks
 ```
 
-Each `*.loki` file reopens `class Tasks`. To load them, pass `--auto-load` to the `asgard` command — they are loaded alphabetically before `.loki`. See [Task Files](task-files.md) for full details.
+Each `*.loki` file reopens `class Tasks`. To load them, call `import "*.loki"` at the top of `.loki` — files are loaded in alphabetical order. See [Task Files](task-files.md) for full details.
 
 ---
 
 ## Built-in Flags
 
-Every task automatically has three flags available, defined as `class_option` on `Tasks`:
+Every task automatically has four flags available, defined as `class_option` on `Tasks`:
 
 | Flag | Description |
 |---|---|
 | `--version` | Print the Asgard version and exit |
 | `--debug` | Set `$DEBUG = true` before the task runs |
 | `--verbose` | Set `$VERBOSE = true` before the task runs |
+| `--doctor` | Diagnose `.loki` resolution, imports, and task definitions for the CWD, then exit |
 
 ```bash
 asgard --version
 asgard hello --debug
 asgard hello --verbose
+asgard --doctor
 ```
 
 Inside a task body, use the `debug?` and `verbose?` predicates:

data/docs/helpers.md

@@ -75,6 +75,90 @@ end
 
 ---
 
+## The `helper` DSL Method
+
+`helper` is an Asgard DSL method that defines a helper available in **both class context and instance context** with a single declaration. It is the right tool when a value needs to be used inside a `header` or `footer` call (which execute at class load time) and also inside task instance methods.
+
+### The problem it solves
+
+Thor task methods run as instance methods. Class-level DSL calls like `header` and `footer` run as class methods. A plain `def` only creates an instance method, so it cannot be called inside `header`. Conversely, `def self.name` only creates a class method, so it cannot be called inside a task body without `self.class.name`.
+
+The manual workaround is verbose:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  # class method for header/footer
+  def self.version
+    @@version ||= File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  end
+
+  # private instance method delegating to the class method
+  no_commands do
+    private def version = self.class.version
+  end
+
+  header "#{@@project} v#{version}"
+
+  desc "Show version"
+  def show_version = puts version
+end
+```
+
+`helper` replaces those six lines with one:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  helper(:version) {
+    @@version ||= File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  }
+
+  header "#{@@project} v#{version}"
+
+  desc "Show version"
+  def show_version = puts version
+end
+```
+
+### Arguments
+
+`helper` supports any argument signature valid in a Ruby method definition: positional, keyword, default values, and blocks.
+
+```ruby
+# No arguments
+helper(:project_root) { loki_up.parent.to_s }
+
+# Positional arguments
+helper(:gem_path) { |name| "lib/#{name}/version.rb" }
+
+# Positional with default
+helper(:tag_prefix) { |sep = "-"| "#{@@project}#{sep}" }
+
+# Positional and keyword arguments
+helper(:format_version) { |name, version, prefix: "v", separator: "-"|
+  "#{prefix}#{name}#{separator}#{version}"
+}
+```
+
+Wrong argument counts or unknown keyword names raise the same `ArgumentError` Ruby raises for any method call — no special error handling needed.
+
+### Visibility
+
+`helper`-defined methods are:
+
+- **Excluded from `asgard help`** — they never appear as commands
+- **Blocked from CLI invocation** — cannot be called directly from the command line
+- **Private on the instance side** — not accessible from outside the class
+
+### When to use `helper`
+
+Use `helper` when the value or computation must be available in both a class-level DSL call (`header`, `footer`, a `@@var` initializer) and inside task instance methods. For helpers that are only needed inside task bodies, a plain `private` method is simpler.
+
+---
+
 ## Choosing Between `private` and `no_commands`
 
 | | `private` | `no_commands` |

data/docs/index.md

@@ -18,7 +18,7 @@
 <li><strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code></li>
 <li><strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories</li>
 <li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files loaded via <code>import</code></li>
-<li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, and <code>--verbose</code> available on every task</li>
+<li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, <code>--verbose</code>, and <code>--doctor</code> available on every task</li>
 </ul>
 </td>
 </tr>
@@ -72,7 +72,7 @@ The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_d
 | [Subcommands](subcommands.md) | Grouping tasks under a namespace |
 | [Shell Helpers](shell.md) | `sh`, `shebang`, and supported interpreters |
 | [Environment](environment.md) | Loading `.env` files with `dotenv` |
-| [Task Files](task-files.md) | `.loki` root marker, `--auto-load`, multi-file layout |
+| [Task Files](task-files.md) | `.loki` root marker, `import`, multi-file layout |
 | [API Reference](api.md) | Module methods, DSL methods, error classes |
 | [Examples](examples.md) | Working `.loki` files for every feature |
 | [Changelog](changelog.md) | Release history |
@@ -82,4 +82,4 @@ The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_d
 ## Requirements
 
 - Ruby >= 3.2.0
-- Dependencies: [thor](https://github.com/rails/thor) `~> 1.0`, [dagwood](https://rubygems.org/gems/dagwood) `~> 1.0`, [dotenv](https://github.com/bkeepers/dotenv) `~> 3.0`
+- Dependencies: [thor](https://github.com/rails/thor) `~> 1.0`, [dotenv](https://github.com/bkeepers/dotenv) `~> 3.0`

data/docs/options.md

@@ -1,6 +1,6 @@
 # Options & Flags
 
-Asgard tasks use the full Thor option system. Options declared with `method_option` (alias: `option`) apply to a single task. Options declared with `class_option` apply to every task in the class. Asgard ships with three built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, and `--version`.
+Asgard tasks use the full Thor option system. Options declared with `method_option` (alias: `option`) apply to a single task. Options declared with `class_option` apply to every task in the class. Asgard ships with four built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, `--version`, and `--doctor`.
 
 ---
 
@@ -71,21 +71,65 @@ end
 
 Both `deploy` and `migrate` automatically accept `--dry-run` and `--env`.
 
+### Boolean class options and `no_negate`
+
+Thor automatically generates `[--no-name]` and `[--skip-name]` help entries alongside every boolean `class_option`. When negation is meaningful — `--dry-run` paired with `--no-dry-run` — this is useful. When negation is meaningless, call `no_negate` immediately after the declaration to remove the extra variants from the help output:
+
+```ruby
+class Tasks
+  class_option :color,
+               type:    :boolean,
+               default: true,
+               desc:    "Colorize output"
+  no_negate :color
+end
+```
+
+Help output before `no_negate`:
+
+```
+[--color], [--no-color], [--skip-color]  # Colorize output
+```
+
+Help output after `no_negate`:
+
+```
+[--color]                                # Colorize output
+```
+
+`no_negate` accepts multiple option names in a single call:
+
+```ruby
+no_negate :color, :version, :emoji
+```
+
+It has no effect on runtime behaviour — `--no-color` still works on the CLI; only the help display is affected.
+
 ---
 
 ## Built-in Flags
 
-`Tasks` ships with three built-in class options and a version flag:
+`Tasks` ships with four built-in `class_option` declarations — `--debug`, `--verbose`, `--version`, and `--doctor` — all visible in the Options section of `asgard help`.
 
 ### `--version`
 
-Prints `Asgard::VERSION` and exits. Implemented as the `_version` method with the `_` prefix convention (gem-owned, blocked from direct CLI invocation):
+A `class_option :version` of type `:boolean`. Prints `Asgard::VERSION` and exits. Handled by `Asgard.run!` before the `.loki` file is loaded, so it works even in a directory without a `.loki` file. `no_negate :version` suppresses the `[--no-version]` / `[--skip-version]` variants (see [Boolean class options and `no_negate`](#boolean-class-options-and-no_negate) above):
 
 ```bash
 asgard --version
-# 0.1.2
+# 0.3.0
 ```
 
+### `--doctor`
+
+A `class_option :doctor` of type `:boolean`. Diagnoses `.loki` resolution, import chains, and task definitions for the current directory, then exits. Handled by `Asgard.run!` before the `.loki` file is loaded (same pattern as `--version`) — deliberately so, since it needs to keep working in the exact situations that would otherwise abort `run!`: a broken `.loki` file, a circular or undefined dependency, or a task silently redefined by a later `def`. The report includes a "Tasks by file" listing — every command grouped by the file it's defined in, as `file:line` — with any silently-overridden task called out inline, right where it's defined. `no_negate :doctor` suppresses the `[--no-doctor]` / `[--skip-doctor]` variants:
+
+```bash
+asgard --doctor
+```
+
+See [`Asgard::Doctor` in the API Reference](api.md#asgarddoctor) for the full breakdown of what it checks.
+
 ### `--debug`
 
 A `class_option :debug` of type `:boolean`. When passed, sets `$DEBUG = true` before the task body runs (via the `invoke_command` hook in `Asgard::Base`):
@@ -173,8 +217,8 @@ asgard deploy production --verbose
 Methods whose names start with `_` are considered gem-owned in Asgard's naming convention. `run!` guards against invoking them directly from the CLI:
 
 ```bash
-asgard _version
-# asgard: unknown command '_version'
+asgard _something
+# asgard: unknown command '_something'
 ```
 
-If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being silently blocked.
+If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being blocked. Built-in `class_option` declarations (like `--version`, `--debug`, `--verbose`, `--doctor`) do not use the `_` prefix because they are options, not commands.

data/docs/task-files.md

@@ -93,7 +93,7 @@ import("gem_tasks.loki") ? "loaded now" : "already loaded"
 
 ## Finding Files with `loki_up`
 
-`loki_up(name = ".loki")` searches `Dir.pwd` and each ancestor directory for a file with the given name, returning its absolute path or `nil`. It does **not** load the file — it only finds it.
+`loki_up(name = ".loki")` searches `Dir.pwd` and each ancestor directory for a file with the given name, returning a `Pathname` or `nil`. It does **not** load the file — it only finds it.
 
 Despite the name, `loki_up` is not limited to `.loki` files — it will locate any file by name. This makes it useful for finding shared config files, `.env` files, or any other resource that lives somewhere up the directory tree:
 
@@ -401,7 +401,7 @@ end
 
 | Method | Finds? | Loads? | Glob? | Ancestor search? |
 |---|---|---|---|---|
-| `loki_up(name)` | Yes | No | No | Yes |
+| `loki_up(name)` | Yes (`Pathname`) | No | No | Yes |
 | `import(path)` | No | Yes | Yes | No |
 | `import_up(name)` | Yes | Yes | Yes | Yes |
 | Asgard's `run!` | Yes | `.loki` only | No | Yes |