asgard 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5752f0e0d294dfb08b809b62b0fbcb4d26f281c6c6a9ddc4ca2b9ae9c310cfc
-  data.tar.gz: 918cbb04f6b285b0d96f674b963cd98c899f151159a73e8ccba72824c8c485f5
+  metadata.gz: 0f88b550d323b26b075a45f6a7d6e8781b7d54d062c1f724de25b2d253d2f3e4
+  data.tar.gz: 5c2a05803003793e14ad08f0453d0a549cb6f2f0202b31c38c600303a539d66b
 SHA512:
-  metadata.gz: d4a32a84315d0367316ea813f5106d55e54c465f8d1ff1ca6958955fd8c23153483a0002a5396af63ad980ec37dacba6c2b3b311516901ff6bd0dc8ecd4dea37
-  data.tar.gz: 87b809a6e2900d22bec4cff5d9b133a4620bf6c2972312c02243bea916aa6cc01dcf668c3ea80786d710ddf39e7e5c3b773d35ec27577253b131a2e0463e1b39
+  metadata.gz: d9f2d214246e0960b2a2a4ca790818a8f57edfd45c17f0fca6edf1bcf486cc096d0331818d899c5ca929f9fcec404329744403a0f03aa2fe0faafb70b13ae172
+  data.tar.gz: e35a52164438b5734cdf86ee4f7210e2169edb391e8478cddd1548698691d3bddea5d703ef113e34bcdd1caeb0041d9851ec94b8ee7840b9115a0ca821f03f49

data/.envrc

@@ -1 +1,6 @@
+# asgard/.envrc
+
+source_up
+
 export RR=`pwd`
+PATH_add $RR/bin

data/.loki

@@ -3,12 +3,25 @@
 # Task is pre-defined by the gem — just reopen it to add tasks.
 
 import "quality.loki"
+# asgard runs as a separate process outside the app it's checking, so
+# `defined?(Rails)` never sees the app's Rails constant. RAILS_ROOT — set in
+# a Rails repo's own .envrc (`export RAILS_ROOT=$RR`, after RR is defined)
+# — is the signal instead.
+import "quality_rails.loki" if ENV["RAILS_ROOT"]
+
 import "gem_tasks.loki"
+import "git.loki"
+import "doc_tasks.loki"
+
+import "xyzzy.loki"  # An example for the --doctor flag
 
 class Tasks
   @@project      ||= "asgard".freeze
   @@project_desc ||= "CLI-task runner"
 
+  desc "xyzzy"
+  def xyzzy = puts "everything in Ruby metaprogramming is magic"
+
   helper(:project_version) do
     @@project_version ||= File.read("lib/#{@@project}/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
   end
@@ -16,7 +29,7 @@ class Tasks
   default_task :quality
 
   header <<~HEAD
-    Porject:  #{@@project} (v#{project_version}) - #{@@project_desc}
+    Project:  #{@@project} (v#{project_version}) - #{@@project_desc}
     Root Dir: #{loki_up.parent}
     Default task: #{default_task}
   HEAD

data/.reek.yml

@@ -0,0 +1,115 @@
+---
+detectors:
+
+  # Disabled: conflicts with project no-comment coding style.
+  IrresponsibleModule:
+    enabled: false
+
+  # Disabled: bang methods without non-bang counterparts are common in internal APIs.
+  MissingSafeMethod:
+    enabled: false
+
+  # Disabled: explicit nil checks are idiomatic Ruby (nil? / unless nil, etc.).
+  NilCheck:
+    enabled: false
+
+  # Disabled: method size/complexity is already covered by Flog (the primary
+  # complexity gate) and RuboCop's Metrics/MethodLength.
+  TooManyStatements:
+    enabled: false
+
+  # Default is 4 — Doctor legitimately tracks several pieces of diagnostic state.
+  TooManyInstanceVariables:
+    max_instance_variables: 6
+
+  # Accept standard Ruby short-name conventions for limited-scope variables.
+  UncommunicativeVariableName:
+    accept:
+      - _    # intentionally ignored
+      - d    # dep / dir / data
+      - e    # rescue => e
+      - f    # file / finding
+      - h    # hash
+      - i    # index
+      - k    # key
+      - p    # path
+      - t    # task / thread
+
+  # Reviewed and accepted as false positives / intentional design, per method
+  # (generated with `reek --todo` and hand-curated — see project review notes).
+  # Unlike a count-based baseline, this is precise: it grandfathers exactly
+  # these smells at exactly these methods, so a genuinely new smell at a new
+  # or existing method still fails the gate even if it doesn't change the
+  # file's total warning count.
+  Attribute:
+    exclude:
+      - Asgard::Doctor::ImportTracer#doctor # needs to stay settable/resettable per doctor run
+
+  BooleanParameter:
+    exclude:
+      - Asgard::Base#help          # must match Thor's positional super signature exactly
+      - Asgard::Shell#sh           # silent: is the real public API contract
+      - Asgard::Shell#shebang      # same
+
+  ControlParameter:
+    exclude:
+      - Asgard::Shell#sh
+      - Asgard::Shell#shebang
+
+  DuplicateMethodCall:
+    exclude:
+      - Asgard::Base::Dispatch#acquire_run_token  # done.include?(target): check, then poll-until-true
+      - Asgard::Base::Dispatch#run_dep_group      # errors.size: two branches of one guard
+      - Asgard::Doctor::Report#print_report       # puts divider: intentional top+bottom rule
+      - Asgard::Doctor::Report#summary_line       # errors.zero?: sequential guard clauses
+      - Asgard::Doctor#load_chain                 # Base.subclasses: before/after snapshot diff
+      - Kernel#import_up                          # "not found" warned from two independent branches
+      - Asgard#self.run!                          # Base.subclasses snapshot diff; e.message in separate rescues
+      - Asgard::Base#tree                          # say "\n": intentional blank line before and after the tree
+
+  FeatureEnvy:
+    exclude:
+      - Asgard::Base::Dispatch#acquire_run_token
+      - Asgard::Base::Dispatch#run_dep_group
+      - Asgard::Base::Dispatch#signal_done
+      - Asgard::Base::Registry#inherited            # inherited(subclass) configuring subclass is the whole point
+      - Asgard::Base::DependencyGraph#_normalize_pending_deps # small transform of its own argument
+      - Asgard::Base::DependencyGraph#_call_dep_proc          # rescue => e; e.class/e.message is inherent
+      - Asgard::Base::DependencyGraph#_validate_dep_stage!    # pure shape check of its own argument
+      - Asgard::Base::DependencyGraph#_validate_dep_leaf!     # pure shape check of its own argument
+      - Asgard::Doctor::TaskSections#class_task_file_map
+      - Asgard::Doctor::TaskSections#relative_path
+      - Asgard::Doctor::TaskSections#task_status
+      - Asgard::Shell#shebang                       # Tempfile.create(&block) idiom
+
+  ManualDispatch:
+    exclude:
+      - Asgard::Base::DependencyGraph#_normalize_pending_deps # respond_to?(:call) distinguishes a Proc from an Array/Symbol — no polymorphic alternative over Ruby's own built-in types
+      - Asgard::Base::DependencyGraph#_resolve_lazy_deps!     # same check
+
+  InstanceVariableAssumption:
+    exclude:
+      - Asgard::Base    # class-level DSL state built up across method_added/inherited, not object init
+      - Asgard::Doctor  # multi-phase report builder; @ivars set across report_markers/load_chain/etc in `run`
+
+  NestedIterators:
+    exclude:
+      - Asgard::Base::DependencyGraph#_build_dep_graph
+      - Asgard::Base::DependencyGraph#_check_dep_arities!
+      - Asgard::Base::TaskDSL#no_negate               # inner block defines a method, isn't really iteration
+      - Asgard::Doctor::Report#print_task_sections
+      - Asgard::Doctor::TaskSections#class_task_file_map
+      - Asgard::Doctor::TaskSections#override_count
+
+  UtilityFunction:
+    exclude:
+      - Asgard::Base::DependencyGraph#_build_dep_graph # genuinely pure, but tightly coupled to this graph model
+      - Asgard::Base::Dispatch#dep_results             # thread-local by design, not self — that's the whole point
+      - Asgard::Base::Dispatch#with_dep_results        # same: stashes results on Thread.current, not self
+      - Asgard::Shell#shell_argv                       # extracted pure on purpose so it's testable without invoking system/exec
+
+exclude_paths:
+  - test
+  - docs
+  - coverage
+  - pkg

data/.rubocop.yml

@@ -6,6 +6,12 @@ AllCops:
     - 'examples/**/*'
     - 'vendor/**/*'
 
+# Archspec.rb's capitalization is mandated by the archspec gem itself, not a
+# style choice — it won't look for a snake_case config file.
+Naming/FileName:
+  Exclude:
+    - 'Archspec.rb'
+
 # ── Style: disabled cops ───────────────────────────────────────────────────
 Style/StringLiterals:
   Enabled: false

data/Archspec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+source "lib/**/*.rb"
+
+component :shell,          in: "lib/asgard/shell.rb"
+component :kernel_methods, in: "lib/asgard/kernel_methods.rb"
+component :base,           in: %w[lib/asgard/base.rb lib/asgard/base/**/*.rb]
+component :tasks,          in: "lib/asgard/tasks.rb"
+component :doctor,         in: %w[lib/asgard/doctor.rb lib/asgard/doctor/**/*.rb]
+
+# The DSL engine must not depend upward on the classes built on top of it —
+# Tasks and Doctor are consumers of Base, never the other way around.
+base.cannot_use :tasks, :doctor
+
+# Built-in/user tasks stay independent of the --doctor introspection feature.
+tasks.cannot_use :doctor
+
+# Shell (sh/shebang helpers, mixed into Base) and the Kernel additions (env,
+# loki_up, import, ...) are leaf-level utilities — they must not depend on
+# anything built on top of them.
+shell.cannot_use :base, :tasks, :doctor
+kernel_methods.cannot_use :base, :tasks, :doctor, :shell
+
+no_cycles among: %i[base tasks doctor shell kernel_methods]

data/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.3.1] - Unreleased
+## [0.3.3] - 2026-08-27
 
 ### Added
 
@@ -103,6 +103,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`loki_up` scope clarified in docs** — `docs/task-files.md` and `docs/api.md` now make explicit that `loki_up` locates any file by name, not just `.loki` files, with examples for `.env` and `VERSION`. The `dotenv loki_up(".env") || ".env"` pattern is shown as the canonical way to load a `.env` file from any subdirectory.
 - **`examples/.loki`** — updated to use explicit `import "*.loki"` (sibling files) and `import "subdir/import_demo.loki"` (subdirectory file), with comments explaining `import`, `import_up`, and `loki_up`.
 
+### Added (continued)
+
+- **`--doctor` built-in CLI flag** — diagnoses `.loki` resolution, import chains, and task definitions for the current directory, then exits. Handled directly in `Asgard.run!` before the `.loki` file is loaded (same pattern as `--version`), so it keeps working in exactly the 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`. Backed by the new `Asgard::Doctor` class. The report includes a "Tasks by file" listing: every command grouped by the file it's defined in, printed as `relative/path:line` so an editor can jump straight to it. A task name defined at more than one location gets every definition annotated inline — the earlier one(s) as `OVERRIDDEN by <file>:<line> — never callable`, the winning (last) one as `active — redefines <file>:<line>` — replacing the old flat "Tasks#x redefined" summary line with an annotation right where the problem is. See [API Reference](docs/api.md#asgarddoctor).
+- **Flay and Reek quality gates** — `flay_check` checks for structural code duplication (mass ≥ 150); `reek` checks code smells. Both run as part of `quality` alongside `test`, `rubocop`, and `flog_check`. A `.reek.yml` tunes several detectors to this codebase's conventions (no doc-comment requirement, short variable names, disabled `TooManyStatements`, etc), plus per-method `exclude:` entries (generated with `reek --todo` and hand-curated) that grandfather specific reviewed smells at specific methods — precise enough that a genuinely new smell still fails the gate even at an already-reviewed method, unlike a per-file count.
+- **`test_verbose` task** — runs the test suite with Minitest's verbose (`-v`) output.
+- **Colorized quality gate summary** — `quality`'s final report now prints a green/red PASS/FAIL badge per gate plus a passed/failed tally, via a shared `print_quality_summary` helper.
+- **`console` task** — opens an IRB console with the gem loaded (`bin/console` if present, otherwise `bundle exec irb`).
+- **`git.loki`** — per-repo git tasks (`push`, `pull`, `fetch`), imported from `.loki`.
+
+### Changed (continued)
+
+- **`release` task** now prompts for confirmation (`Release asgard vX.Y.Z to RubyGems? [y/N]`) unless `-y`/`--yes` is passed, before tagging and pushing.
+
+### Fixed (continued)
+
+- **`bin/asgard` could silently run the wrong `asgard` version** — the executable did `require "asgard"`, which (without `bundle exec`) is resolved by RubyGems independently of where the script itself lives, so it could load a separately-installed gem version instead of this repo's own `lib/`. Changed to `require_relative "../lib/asgard"` so the executable always loads the library that ships alongside it, regardless of what else is installed.
+
+### Added (continued 2)
+
+- **`SKIP` and `WARN` quality-gate statuses** — alongside `PASS`/`FAIL`. Both are non-blocking (`quality` only aborts on `FAIL`); `SKIP` is for a required external tool that isn't installed, `WARN` is for a check that ran successfully but has non-blocking suggestions. `print_quality_summary` renders all four with distinct colored badges and a combined tally.
+- **`typos_check` / `typos_fix` tasks** — spell-checking via the external `typos` CLI (`brew install typos-cli`, not a gem dependency). `typos_check` writes full findings to `typos_output.txt` and participates in `quality`. If `typos` isn't installed, the gate prints a one-line notice recommending `brew install typos-cli` and reports `SKIP` rather than failing.
+- **`fasterer_check` task** — runs the `fasterer` gem (new dev dependency) against `lib/`, reporting performance-idiom suggestions as `WARN` (non-blocking) — these are suggestions on working code, not correctness problems.
+- **`asgard tree` now shows the project header/footer** — `Base#tree` wraps Thor's built-in command tree the same way `Base#help` already wraps the command list, so both example outputs are consistent.
+- Every quality gate (`test_check`, `rubocop_check`, `flog_check`, `flay_check`, `reek_check`, `typos_check`, `fasterer_check`, `bundler_audit_check`) now writes its full detailed output to a `<gate>_output.txt` file at the repo root (gitignored via `*_output.txt`) and prints only a one-line summary to stdout — full detail stays on disk without cluttering the terminal.
+
+### Changed (continued 2)
+
+- **`Asgard::Base` and `Asgard::Doctor` split into focused mixins** — `Asgard::Base` (31 methods) is now `Registry`, `DependencyGraph`, `TaskDSL`, and `Dispatch` (`lib/asgard/base/*.rb`), with `method_added`/`header`/`footer`/`help`/`tree` remaining directly on the class as the orchestrator. `Asgard::Doctor` (19 methods) is now `TaskSections` and `Report` (`lib/asgard/doctor/*.rb`), with the diagnostic flow (`run`, `report_markers`, `load_chain`, etc.) staying on the class itself. Purely a file-organization change — behavior, `asgard help`/`asgard --doctor` output, and the public API are unchanged. Drops Reek's `TooManyMethods`/`TooManyInstanceVariables` warnings on both classes to zero.
+- **Reek grandfathering made precise** — replaced the per-file smell-count baseline (`.quality/reek_baseline.txt`, the `reek_baseline` task) with per-method, per-detector `exclude:` entries in `.reek.yml` itself, generated via `reek --todo` and hand-curated. Unlike a count, this still catches a genuinely new smell at an already-reviewed method, without relying on the file's total count staying the same. The `reek_baseline` and `ensure_quality_dir` tasks and the `.quality/` directory have been removed as no longer needed.
+
+### Added (continued 3)
+
+- **`depends_on` accepts a Proc/lambda in addition to a fixed list** — a sole callable defers resolution to `validate_deps!` (once, right after every `.loki` file has loaded) instead of resolving immediately when `depends_on` itself is evaluated. This solves the "load order matters" problem for a dependency list that can't be known upfront — e.g. "every task whose name ends in `_check`," discovered across several files including ones imported conditionally (`import "quality_rails.loki" if defined?(Rails)`). The Proc must return the same shape the splat form would receive (an array of stages, each a `Symbol` or `Array`); it's written directly in the class body, so it lexically captures that class as `self` and can call `all_commands` bare. A Proc that raises is re-raised as `Asgard::Error` naming the task it was declared for; a Proc that resolves to an undefined task or a cycle is still caught by the existing startup validation, since the resolved result is checked exactly like a plain array. See [Dynamic Dependencies](docs/dependencies.md#dynamic-dependencies-proc-form).
+- **`bundler_audit_check` task** — runs `bundle-audit check --update` against `Gemfile.lock` (new dev dependency `bundler-audit`); reports `FAIL` on any known vulnerability, since this is a security gate, not a suggestion.
+- **`quality_rails.loki`** — imported by `.loki` only when `Rails` is defined; currently ships `brakeman_check`, a Rails security-scan example. Needs no wiring into `quality`'s dependency list — `quality`'s `depends_on` Proc discovers it automatically once it's loaded.
+
+### Changed (continued 3)
+
+- **`test`, `rubocop`, `reek` renamed to `test_check`, `rubocop_check`, `reek_check`** — for consistency with the other gates, all of which already ended in `_check`. This convention is what makes automatic discovery possible: `quality`'s `depends_on` Proc finds every task whose name matches `_check\z` rather than naming them one by one.
+
+### Removed (continued)
+
+- **`dagwood` runtime dependency** — replaced by stdlib `TSort` for the one thing it was still doing (cycle detection); the parallel-execution plan itself was already derived directly from `depends_on`'s stage list, not from a rebuilt DAG. `_build_dep_graph` (dead code — its return value was already unused) is deleted along with the gemspec entry.
+
+### Changed (continued 4)
+
+- **`validate_deps!` cycle detection now uses stdlib `TSort`** instead of `Dagwood::DependencyGraph#order` — a private `Graph` `Struct` (`edges` member, `include TSort`) owns the task→dependency Hash and the traversal, raising `TSort::Cyclic` on a cycle exactly as before (converted to `Asgard::CircularDependencyError`). `run_deps_for` no longer round-trips through a rebuilt DAG on every dispatch — it iterates `_deps[target]`'s stage groups directly, which is already the parallel-execution plan `depends_on` built.
+
+### Fixed (continued 2)
+
+- **`quality.loki`'s parallel `*_check` tasks raced on shared instance state** — each `*_check` task wrote its pass/fail status to an ivar on `self` (`@test_result`, `@rubocop_result`, ...) from inside a `Thread.new` spawned by the same parallel-dependency group — an unsynchronized write across threads that MRI's GVL happens to hide today but would not on JRuby/TruffleRuby. Fixed at the framework level: `Dispatch#run_dep_group` now collects each task's own return value into a `Hash` (via `Thread#value`), `run_deps_for` merges per-stage results, and a new `dep_result`/`dep_results` instance API (backed by `Thread.current`, not `self`) hands them to the task body that depends on them. `quality.loki` and `quality_rails.loki`'s `*_check` tasks now return their status as a plain value instead of writing to an ivar; `quality` reads `dep_result(name)` instead of `instance_variable_get`.
+
+### Added (continued 4)
+
+- **`examples/bad.loki`** — a worked demonstration of the race the fix above addresses: 4 parallel workers read-modify-write a shared `@hits` counter directly (the anti-pattern `quality.loki` used to have), reliably losing updates. Kept as a contrast example for what `dep_result`/`dep_results` is for.
+
+### Added (continued 5)
+
+- **`sh(script, exec: true)`** — hands the command the asgard process itself via `Kernel.exec` instead of forking. For a task's final, long-running command (a dev server, a REPL) this replaces the ruby process outright, so nothing sits resident in memory behind it and Ctrl-C is handled directly by the command instead of unwinding back through asgard. `doc_tasks.loki`'s `doc_server` task (`sh "mkdocs serve", exec: true`) is the motivating example. See [Shell Helpers](docs/shell.md#handing-off-with-exec).
+- **`bootstrap` and `env_info` tasks in `kitchen_sink.loki`** — demonstrate `sh` with a multi-line heredoc (routed through `bash -c`) and a single-line command, respectively.
+
+### Fixed (continued 3)
+
+- **Ctrl-C during a running `sh` command printed a raw `Interrupt` backtrace** — SIGINT hits the whole foreground process group, so asgard's own ruby process raised `Interrupt` independently of whatever the shelled-out command did with the signal, and it went uncaught, unwinding through Thor and printing a stack trace before exiting. `Asgard.run!` now rescues `Interrupt` and exits with the conventional 130 status.
+
+### Added (continued 6)
+
+- **`depends_on` accepts a block in addition to a Proc/lambda** — `depends_on { ... }` (or `depends_on do ... end` for a block spanning multiple statements) defers resolution to `validate_deps!` exactly like the existing sole-Proc/lambda form; the two are interchangeable. `depends_on` still accepts task arguments *or* a block, never both — combining them raises `Asgard::Error`. See [Dynamic Dependencies](docs/dependencies.md#dynamic-dependencies-proc-block-form).
+- **The resolved Proc/lambda/block result is now shape-validated** — once `validate_deps!` calls it, the return value must be an `Array` of stages, each a `Symbol`/`String` (sequential) or an `Array` of `Symbol`/`String` (parallel group), nested no deeper than that. A bad shape (wrong type, an invalid stage, a non-Symbol/String leaf, or nesting more than one level deep) now raises `Asgard::Error` naming the task and the offending value, instead of failing later with an opaque `NoMethodError`.
+- **`examples/depends_on_block/good/` and `examples/depends_on_block/bad/`** — two self-contained example projects (each its own `.loki` root, isolated from the main `examples/` tree) demonstrating the block form: `good/` covers single-line `{ ... }`, `do...end`, and a mixed sequential+parallel shape; `bad/` demonstrates the double-wrapped-array mistake that the new shape validation catches, with the exact `Asgard::Error` message it produces.
+
 ## [0.2.0] - 2026-05-29
 
 ### Changed

data/CLAUDE.md

@@ -16,7 +16,7 @@ bundle exec rake build         # build .gem into pkg/
 bundle exec rake install       # install locally
 
 # or use the gem's own .loki file:
-asgard test
+asgard test_check
 asgard quality
 asgard release
 ```
@@ -72,16 +72,13 @@ depends_on :a, [:b, :c], :d   # stages: [[:a], [:b, :c], [:d]]
 
 **`invoke_command`** (Thor dispatch hook):
 1. Atomically check `@_ran_tasks` Set (with `@_ran_mutex`); return early if already run
-2. Resolve `@_deps` stages → `_build_dep_graph` → `Dagwood::DependencyGraph#parallel_order`
-3. For each parallel group: spawn one thread per task, join; single-task groups run inline
+2. Look up `@_deps[target]` — already the parallel-group stage list `depends_on` built
+3. For each stage group: spawn one thread per task, join; single-task groups run inline
 4. Execute the target task
 
-**`_build_dep_graph(stages)`** converts stages to a DAG hash:
-- `[[:a], [:b, :c], [:d]]` → `{ a: [], b: [:a], c: [:a], d: [:b, :c] }`
-
 ### Dependency Resolution
 
-Dagwood topologically sorts the DAG and returns parallel groups. The thread-safe deduplication (`_ran_tasks` Set + Mutex) ensures each task runs exactly once even when multiple tasks share a common dependency.
+`depends_on`'s stage list (`[[:a], [:b, :c], [:d]]`) *is* the parallel-execution plan — no separate graph library is needed to run it. Cycle detection is a separate concern, handled once in `validate_deps!` via stdlib `TSort` over the full `@_deps` graph (raises `TSort::Cyclic`, converted to `Asgard::CircularDependencyError`). The thread-safe deduplication (`_ran_tasks` Set + Mutex) ensures each task runs exactly once even when multiple tasks share a common dependency.
 
 ### Shell Helpers
 

data/README.md

@@ -23,7 +23,7 @@
 - <strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code><br>
 - <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
 - <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
-- <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, and <code>--version</code> built-in class options; header/footer DSL for static help text<br>
+- <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, <code>--version</code>, and <code>--doctor</code> built-in class options; header/footer DSL for static help text<br>
 </td>
 </tr>
 </table>
@@ -221,6 +221,29 @@ asgard ci executes:
   ci
 ```
 
+`depends_on` also accepts a `Proc`/lambda (or, equivalently, a block) instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately — useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
+
+```ruby
+depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+def quality = puts "running every *_check task..."
+
+depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+def quality2 = puts "same, as a block..."
+
+# do...end for a block spanning multiple statements — braces are for
+# single-line blocks like the two above. The last expression is still what
+# gets returned and validated.
+depends_on do
+  checks = all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)
+  slow   = %i[c_check]
+
+  [checks - slow]
+end
+def quality3 = puts "same, minus the slow checks, as a multi-line block..."
+```
+
+See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-block-form) for the full explanation.
+
 ---
 
 ## Variables
@@ -480,6 +503,33 @@ end
 
 ---
 
+## Abbreviated command matching
+
+Every task is a Thor command, so you don't have to type the full name — Thor resolves any unambiguous prefix automatically, with no extra code:
+
+```ruby
+class Tasks
+  desc "Compile the project"
+  def build = sh "rake build"
+
+  desc "Deploy to production"
+  def deploy = sh "cap production deploy"
+
+  desc "Deploy to staging"
+  def deploy_staging = sh "cap staging deploy"
+end
+```
+
+```bash
+asgard b        # same as: asgard build   — only task starting with "b"
+asgard depl     # Ambiguous command depl matches [deploy, deploy_staging]
+asgard deploy   # runs deploy — an exact match always wins, even over a shorter ambiguous prefix
+```
+
+This is Thor's own dispatch behavior, not an Asgard feature — it applies to every task in every `.loki` file automatically. When a prefix matches more than one task, Thor lists the candidates instead of guessing; type enough of the name to disambiguate, or use `map` (below) to pin a short name that stays stable even if a later-added task would otherwise make it ambiguous.
+
+---
+
 ## Command aliases
 
 `map` creates alternative names for a task:

data/bin/asgard

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "asgard"
+require_relative "../lib/asgard"
 Asgard.run!(ARGV)

data/doc_tasks.loki

@@ -0,0 +1,21 @@
+# dev/doc_tasks.loki
+
+# TODO: create common tasks for documentation management
+class Tasks
+
+  if File.exist?(ENV['RR']+'/.config/tocer/configuration.yml')
+    desc "Management table of contents"
+    def tocer = sh "tocer help"
+  end
+
+
+  if File.exist?(ENV['RR']+'/mkdocs.yml')
+    desc "Documentation builder"
+    def doc_builder = sh "mkdocs build"
+
+    desc "Documentation server startup"
+    depends_on :doc_builder
+    def doc_server = sh "mkdocs serve", exec: true
+  end
+
+end

data/docs/api.md

@@ -111,16 +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, &block)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. A sole `Proc`/lambda, or a block in place of the splat args, defers resolution to `validate_deps!` (after every `.loki` file has loaded) instead of resolving immediately — see [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form). Passing both task arguments and a block raises `Asgard::Error`. |
 | `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. |
+| `sh` | `sh(script, silent: false, exec: 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. With `exec: true`, replaces the asgard process via `Kernel.exec` instead of forking — see [Shell Helpers](shell.md#handing-off-with-exec). |
 | `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
@@ -128,8 +174,16 @@ 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 (or, equivalently, a block) defers resolution to
+# validate_deps!, after every .loki file has loaded — must return the same
+# shape the splat form above would; the shape is validated when it resolves.
+depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
 ```
 
+See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form) for the full explanation of the Proc/block form — why it exists, when it runs, and how errors are reported.
+
 ---
 
 ## `Tasks` Built-ins
@@ -141,11 +195,78 @@ 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`. |
 | `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.
@@ -157,7 +278,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. |
 
 ---
 
@@ -167,7 +287,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.
 
@@ -197,7 +317,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 |
 
 ---