asgard 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6045b69a572bacdc07c1ae149f2978000fb690c180cf536512caf4714345317
-  data.tar.gz: defa5899f4e66143fe3118d835c60f128534075d2ce4a41652a0bbf54f61e790
+  metadata.gz: 8cec41525d2a749cb83bcd59a480fb4bbffa80e468ca4a35c453376a16c84640
+  data.tar.gz: 997da94f3b7bf4fadedaff8d78741ff2748b00fb7107b27402dc50cf73f897df
 SHA512:
-  metadata.gz: 8d27eb2c214be342a64561c8f2287cd05aa48a30e411676dbd69b20f36ec9b706456d7c805c3bfa3a4b64897b8f79831a0a55b96c38b77e3981de551c8737750
-  data.tar.gz: 6bbd01f8c90195fc9b7428dbe7b56721a70d9ffe4b881853497df84c68db7d96400cb279ab9006ff3b6841ab85bd5f54d6838f3d887469331dbe04873bd5dca5
+  metadata.gz: d189e34cd3733b41e436460367130fa19451bf3938b693f1c5663a1268fab41f87866063e2c0c3a185a69dfda238aa8a5e6a253de9bbac0e2c5e97e6c9d2fa6e
+  data.tar.gz: d6fcbee1e4302dce37d7ea39cf22019ae0322f3f200e4ac5421ac247d7facca205e38cdb1f905ab20781142472b0010c46ff966dbba83be918a7fbabd49bebbd

data/.envrc

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

data/.loki

@@ -2,33 +2,29 @@
 # Asgard gem's own task file.
 # Task is pre-defined by the gem — just reopen it to add tasks.
 
-class Tasks
-  @@gem_name ||= "asgard".freeze
+import "quality.loki"
+import "quality_rails.loki" if defined?(Rails)
 
-  desc "Run the test suite"
-  def test
-    sh "bundle exec rake test"
-  end
+import "gem_tasks.loki"
+import "git.loki"
+import "xyzzy.loki"  # An example for the --doctor flag
 
-  desc "Run all quality gates (tests, RuboCop, Flog)"
-  def quality
-    sh "bundle exec rake quality"
-  end
+class Tasks
+  @@project      ||= "asgard".freeze
+  @@project_desc ||= "CLI-task runner"
 
-  desc "Build the gem package"
-  def build
-    sh "bundle exec rake build"
-  end
+  desc "xyzzy"
+  def xyzzy = puts "everything in Ruby metaprogramming is magic"
 
-  depends_on :test
-  desc "Build and install gem locally"
-  def install
-    sh "bundle exec rake install"
+  helper(:project_version) do
+    @@project_version ||= File.read("lib/#{@@project}/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
   end
 
-  depends_on :quality
-  desc "Release to RubyGems"
-  def release
-    sh "bundle exec rake release"
-  end
+  default_task :quality
+
+  header <<~HEAD
+    Project:  #{@@project} (v#{project_version}) - #{@@project_desc}
+    Root Dir: #{loki_up.parent}
+    Default task: #{default_task}
+  HEAD
 end

data/.reek.yml

@@ -0,0 +1,112 @@
+---
+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::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
+
+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,10 +5,50 @@ 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.0] - Unreleased
+## [0.3.2] - Unreleased
 
 ### Added
 
+- **`helper(name, &block)` DSL method on `Asgard::Base`** — defines a method available in both class context (e.g. inside `header` or `footer`) and as a private instance method inside task bodies, with a single declaration. Eliminates the manual `def self.name` + `no_commands { private def name = self.class.name }` boilerplate. Supports positional arguments, keyword arguments, default values, and block arguments.
+  ```ruby
+  class Tasks
+    @@project ||= "myapp".freeze
+
+    helper(:version) {
+      File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+    }
+
+    header "#{@@project} v#{version}"   # class context
+
+    desc "Show the current version"
+    def show_version = puts version     # instance context
+  end
+  ```
+
+- **`header(text)` and `footer(text)` DSL methods on `Asgard::Base`** — attach static text to the general help output. `header` lines are printed above the commands list; `footer` lines are printed below the options block. Multiple calls accumulate: each `header` call appends a line, each `footer` call prepends a line, so content from later-loaded files naturally wraps around content from earlier files. Neither appears when `asgard help <command>` is called for per-command detail.
+  ```ruby
+  class Tasks
+    header "my-project — build & release tasks"
+    footer "See https://example.com/docs for details"
+  end
+  ```
+- **`no_negate(*names)` DSL method on `Asgard::Base`** — suppresses the `[--no-name]` and `[--skip-name]` negation variants from help output for boolean class options where negation is meaningless. Call it after the `class_option` declaration:
+  ```ruby
+  class_option :version, type: :boolean, default: false, desc: "Show version and exit"
+  no_negate :version
+  ```
+
+### Changed
+
+- **`--version` reimplemented as a `class_option`** — the flag now appears in the "Options" section of `asgard help` alongside `--debug` and `--verbose`, rather than as a listed command. The `_version` method and its `map "--version" => :_version` registration have been removed. The actual early-exit behaviour still lives in `Asgard.run!` (before the `.loki` file is required), so `--version` works even when no `.loki` file exists. `no_negate :version` suppresses the spurious `[--no-version]` / `[--skip-version]` variants.
+- **`loki_up` returns `Pathname` instead of `String`** — the return value is now a `Pathname` instance (or `nil` when not found). `Pathname` is accepted everywhere `loki_up`'s result is used: `import`, `dotenv`, `load`, and standard Ruby file methods all accept `Pathname` via `to_path` / `to_s`. Code that passes the result directly to those methods is unaffected; code that performs string operations on the path should call `.to_s` first.
+
+### Fixed
+
+- **Help output showed `tasks` prefix before every command** — `asgard help` displayed `asgard tasks build` instead of `asgard build`. The cause was a keyword-vs-positional mismatch in the `Asgard::Base#help` override: declaring `subcommand: false` as a keyword argument caused Ruby's `super` to forward it as the hash `{subcommand: false}`. Thor's `banner` method received this hash as the positional `subcommand` argument, treated it as truthy, and prepended the class namespace (`tasks`) to every command name. Fixed by changing the override signature to match Thor's positional signature: `def help(command = nil, subcommand = false)`.
+
+### Added (continued)
+
 - **`loki_up(name = ".loki")` Kernel method** — searches `Dir.pwd` and each ancestor directory for a file with the given name; returns the absolute path of the first match or `nil`. Available everywhere in Ruby (task bodies, `.loki` files, top-level code) as a `module_function` on `Kernel`.
 - **`import(path)` Kernel method** — loads a `.loki` file (or a glob of `.loki` files) with `require`-like idempotency via `$LOADED_FEATURES`. Accepts a `String` or `Pathname`. Relative paths are resolved relative to the caller's file (like `require_relative`). Glob patterns (`*.loki`, `**/*.loki`) expand via `Dir.glob` and load all matches. Returns `true` if any file was newly loaded, `false` if all were already loaded or no glob matches were found. Raises `ArgumentError` if the path does not end with `.loki`.
 - **`import_up(name = ".loki")` Kernel method** — combines `loki_up` and `import`. For exact names, finds the first ancestor directory containing that file and loads it. For glob names, finds the first ancestor directory containing any matching files and loads them all — stopping at that level rather than aggregating across multiple ancestors. Returns `false` if nothing is found.
@@ -16,7 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`env(name, default = nil)` Kernel method** — fetches a system environment variable by symbol or string name, upcasing the key automatically. `env(:port, "3000")` returns `"3000"` when `PORT` is unset; `env(:api_key)` raises `KeyError` when `API_KEY` is missing and no default is provided. Accepts both `env(:port)` and `env("PORT")` forms. Cleaner than `ENV['PORT']` in task bodies.
 - **Verbose/debug feedback for `import` and `import_up`** — when `verbose?` is true, each file loaded is printed to stderr. When `debug?` is true, already-loaded files are also reported (with an "already loaded" suffix), and `import_up` reports when a file is not found.
 - **RuboCop lint gate** — RuboCop is now a first-class quality gate alongside tests and Flog. Added `rubocop` to the Gemfile, a `.rubocop.yml` tuned for this codebase (Ruby 3.2 target, relaxed `Metrics` thresholds consistent with Flog as the primary complexity gate, `examples/` excluded), and `rake rubocop` / `rake rubocop_fix` tasks backed by a `tmp/rubocop_cache` directory for fast re-runs.
-- **Expanded `rake quality` task** — `quality` now runs three independent gates (tests + coverage, RuboCop, Flog) and prints a formatted pass/fail summary table after all gates complete, so every failure is visible in a single run rather than stopping at the first.
+- **Expanded `rake quality` task** — `quality` now runs three independent gates (tests + coverage, RuboCop, Flog) in parallel using `depends_on [:test, :rubocop, :flog_check]`. Each gate captures its pass/fail result in an instance variable; output is suppressed on pass and filtered to failures only on fail, preventing interleaved output from concurrent subprocesses. A formatted pass/fail summary table is printed after all gates complete, so every failure is visible in a single run.
 - **`rake flog_check` task** — replaces the bare `flog lib/` call with a structured task that enforces per-method thresholds (warn ≥20, fail ≥50), lists warnings and failures in separate sections, and exits non-zero only when the failure threshold is breached.
 - **Single-argument `desc` shorthand** — `desc` now accepts one string (the description) with the usage string omitted. The usage defaults to the method name, eliminating the redundant first argument for the common case:
   ```ruby
@@ -63,6 +103,62 @@ 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.
+
 ## [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

@@ -18,11 +18,12 @@
 - <strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads<br>
 - <strong>Subcommands</strong> — group related tasks under a named namespace<br>
 - <strong>Variables</strong> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
+- <strong>`helper` DSL</strong> — define a method once, available in both class-level DSL calls (<code>header</code>) and inside task instance methods<br>
 - <strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts<br>
 - <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> and <code>--verbose</code> available on every task; <code>--version</code> at the top level<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>
@@ -220,6 +221,15 @@ asgard ci executes:
   ci
 ```
 
+`depends_on` also accepts a `Proc`/lambda 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..."
+```
+
+See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-form) for the full explanation.
+
 ---
 
 ## Variables
@@ -274,6 +284,40 @@ class Tasks
 end
 ```
 
+### The `helper` DSL method
+
+Some values need to be available in both class context (e.g. inside `header`) and inside task instance methods. `helper` defines the method once in both contexts:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  helper(:version) {
+    File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  }
+
+  header "#{@@project} v#{version}"   # class context
+
+  desc "Show the current version"
+  def show_version
+    puts version                        # instance context
+  end
+end
+```
+
+Without `helper`, achieving this requires two separate definitions:
+
+```ruby
+def self.version = File.read(...).match(...)[1].freeze
+no_commands { private def version = self.class.version }
+```
+
+`helper` accepts positional arguments, keyword arguments, and blocks — any signature valid in a Ruby method definition:
+
+```ruby
+helper(:tag) { |name, ver, prefix: "v"| "#{prefix}#{name}-#{ver}" }
+```
+
 Helpers can also be shared across multiple `.loki` files by extracting them into a plain Ruby file and loading it explicitly:
 
 ```ruby
@@ -299,6 +343,53 @@ end
 
 ---
 
+## Help header and footer
+
+Add static text above and below the command list in `asgard help` output:
+
+```ruby
+class Tasks
+  header "my-project — build & release tasks"
+  footer "See https://example.com/docs for details"
+end
+```
+
+Multiple calls accumulate. `header` appends each line (top to bottom); `footer` prepends each line (bottom to top), so content from a later-loaded `.loki` file sits closer to the commands:
+
+```ruby
+# .loki
+class Tasks
+  header "my-project"
+  footer "Maintainer: you@example.com"
+end
+
+import "*.loki"
+
+# deploy.loki
+class Tasks
+  header "  deploy targets: staging, production"
+  footer "See runbook at wiki/deploy"
+end
+```
+
+```
+my-project
+  deploy targets: staging, production
+
+Commands:
+  ...
+
+Options:
+  ...
+
+See runbook at wiki/deploy
+Maintainer: you@example.com
+```
+
+Header and footer text is only shown for the general `asgard help` page, not for `asgard help <command>`.
+
+---
+
 ## Options shared across all tasks
 
 `class_option` defines an option available to every task in the class:
@@ -566,7 +657,7 @@ end
 | Method | Description |
 |---|---|
 | `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
-| `Asgard.find_task_file` | Returns path to `.loki` searching from CWD upward, or nil |
+| `Asgard.find_task_file` | Returns a `Pathname` to `.loki` searching from CWD upward, or `nil` |
 
 `run!` handles its own errors — a missing `.loki`, a circular dependency, or a `depends_on` that names a task that doesn't exist all produce a clean one-line message and exit 1.
 

data/bin/asgard

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