asgard 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cec41525d2a749cb83bcd59a480fb4bbffa80e468ca4a35c453376a16c84640
-  data.tar.gz: 997da94f3b7bf4fadedaff8d78741ff2748b00fb7107b27402dc50cf73f897df
+  metadata.gz: 0fd4fe5903f93e062c0f515b3f6a49b859671c679b066003c04f2012eaf7176c
+  data.tar.gz: 5af1e1b65fc854258a68ec98a220d8260720474d9d84a7644cecec2fc054889f
 SHA512:
-  metadata.gz: d189e34cd3733b41e436460367130fa19451bf3938b693f1c5663a1268fab41f87866063e2c0c3a185a69dfda238aa8a5e6a253de9bbac0e2c5e97e6c9d2fa6e
-  data.tar.gz: d6fcbee1e4302dce37d7ea39cf22019ae0322f3f200e4ac5421ac247d7facca205e38cdb1f905ab20781142472b0010c46ff966dbba83be918a7fbabd49bebbd
+  metadata.gz: eb251bfc200af2b94dc66e6247475f2a4c0d2a474d0f1d4b165caf05250c8dbb55bd31295b2c0b7e963aeace88f2b8f2c2ecb8751271a522ea5c7a99486bccfe
+  data.tar.gz: c2540f86218ca5fe471ca276081d23224b2bf4f5784862915bf69f21c83acf664ef57f051bb4587a7104d0bb0bf82e768f28acc9b5f3e2cc32d15eac902dbf94

data/.loki

@@ -3,10 +3,16 @@
 # Task is pre-defined by the gem — just reopen it to add tasks.
 
 import "quality.loki"
-import "quality_rails.loki" if defined?(Rails)
+# 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

data/.reek.yml

@@ -44,6 +44,7 @@ detectors:
   Attribute:
     exclude:
       - Asgard::Doctor::ImportTracer#doctor # needs to stay settable/resettable per doctor run
+      - Asgard::Schedule#runner                     # test seam: tests swap in a recording runner, nil restores RUNNER
 
   BooleanParameter:
     exclude:
@@ -55,6 +56,7 @@ detectors:
     exclude:
       - Asgard::Shell#sh
       - Asgard::Shell#shebang
+      - Asgard::Schedule#entry_name                 # as: is the user's explicit override of the derived name
 
   DuplicateMethodCall:
     exclude:
@@ -66,6 +68,7 @@ detectors:
       - 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
+      - Asgard::Schedule::Launchd#unload             # loaded?(name): check, then poll until bootout finishes
 
   FeatureEnvy:
     exclude:
@@ -75,6 +78,8 @@ detectors:
       - 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
@@ -84,6 +89,7 @@ detectors:
     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
+      - Asgard::Schedule#seconds                         # duck-types ActiveSupport::Duration (in_seconds) without depending on it
 
   InstanceVariableAssumption:
     exclude:
@@ -98,12 +104,48 @@ detectors:
       - Asgard::Doctor::Report#print_task_sections
       - Asgard::Doctor::TaskSections#class_task_file_map
       - Asgard::Doctor::TaskSections#override_count
+      - Asgard::Schedule::Commands#preview            # specs x files per spec
+      - Asgard::Schedule::Launchd#self.calendar_intervals # times x weekdays
 
   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
+      - Asgard::Schedule::DSL#schedule                 # class-level DSL delegating to the Schedule registry
+      - Asgard::Schedule::Commands#schedules           # Thor no_commands helpers: reads of the registry / CWD shared by the subcommands
+      - Asgard::Schedule::Commands#schedule_root
+      - Asgard::Schedule::Commands#schedule_summary
+
+  # Asgard::Schedule: the backends implement a fixed API (see
+  # lib/asgard/schedule/declaration.rb) plus pure, separately tested helpers,
+  # and the keyword parameters below mirror launchd/systemd job fields and the
+  # `schedule` DSL's own keywords.
+  DataClump:
+    exclude:
+      - Asgard::Schedule                            # at:/on: and task/args are the declaration's vocabulary
+
+  LongParameterList:
+    exclude:
+      - Asgard::Schedule#normalize                  # the `schedule` DSL keywords
+      - Asgard::Schedule#describe
+      - Asgard::Schedule#program_arguments
+      - Asgard::Schedule::Launchd#self.plist        # one keyword per plist field
+      - Asgard::Schedule::Systemd#self.service_unit # one keyword per unit field
+      - Asgard::Schedule::Systemd#self.timer_unit
+      - Asgard::Schedule::Systemd#initialize        # injectable home/runner/env/user for tests
+
+  RepeatedConditional:
+    exclude:
+      - Asgard::Schedule::Launchd                   # loaded?(name) guards distinct launchctl transitions
+
+  TooManyMethods:
+    exclude:
+      - Asgard::Schedule::Commands                  # one method per subcommand plus its helpers
+      - Asgard::Schedule::Launchd                   # backend API + pure helpers
+      - Asgard::Schedule::Systemd
+
 
 exclude_paths:
   - test

data/CHANGELOG.md

@@ -5,7 +5,47 @@ 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.2] - Unreleased
+## [0.4.0] - 2026-09-26
+
+### Added
+
+- **Scheduled tasks, built in** — `schedule :task, at: "17:30", on: :weekdays`
+  (or `every: 3600`) at class level in a `.loki` declares a periodic run, and
+  `asgard schedule preview|install|list|start|stop|trigger|log|remove`
+  manages the entries under launchd (macOS) or systemd user timers (Linux).
+  Missed calendar runs fire on wake; a project `.envrc` is loaded at run time
+  through `direnv exec`. Promoted from the standalone `dev/schedule.loki`;
+  job labels and paths are unchanged, so entries it installed are still
+  recognized. ActiveSupport is no longer required: `every:` takes seconds or
+  any object with `in_seconds`. The command is registered as the gem-owned
+  `_schedule` and mapped to `schedule`. See
+  [Scheduled Tasks](https://madbomber.github.io/asgard/schedule/).
+- **`Asgard::Schedule::Error`** (subclass of `Asgard::Error`) — raised when
+  `launchctl`/`systemctl` fails; `Asgard.run!` reports it as a one-line
+  `asgard: ...` message.
+
+### Changed
+
+- **Upgrading from `dev/schedule.loki`:** remove `import_up "dev/schedule.loki"`
+  from your `.loki`. Its `Tasks.schedule` overrides the built-in one and
+  records declarations where `asgard schedule` never looks.
+- `Asgard::Error` and `Asgard::CircularDependencyError` now live in
+  `lib/asgard/errors.rb`, loaded first. No change to the classes themselves.
+- The gem's own test run (`test_check`, `test_verbose`) loads every
+  `test/test_*.rb` in one process, so coverage is measured across the whole
+  suite.
+
+### Fixed
+
+- **`asgard <task>` now exits 1 when the task returns `:fail`** — quality-gate
+  tasks (`*_check`) signal failure by returning `:fail`; previously that result
+  was discarded and asgard always exited 0, so callers relying on the exit
+  status (CI, cross-repo runners like `ws_quality.loki`) saw every individual
+  gate as passing. The aggregate `quality` task was unaffected (it aborts
+  itself). Only a top-level result of exactly `:fail` maps to exit 1; `:warn`
+  and `:skip` remain non-blocking.
+
+## [0.3.3] - 2026-08-27
 
 ### Added
 
@@ -105,7 +145,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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).
+- **`--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](https://madbomber.github.io/asgard/api/#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.
@@ -135,7 +175,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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).
+- **`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](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-block-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.
 
@@ -159,6 +199,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`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](https://madbomber.github.io/asgard/shell/#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](https://madbomber.github.io/asgard/dependencies/#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
@@ -236,7 +291,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 100% test coverage enforced via SimpleCov (95% minimum threshold)
 - Quality task in `.loki` runs flog after tests
 
-[0.3.0]: https://github.com/MadBomber/asgard/compare/v0.2.2...HEAD
+[0.4.0]: https://github.com/MadBomber/asgard/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/MadBomber/asgard/compare/v0.2.0...v0.3.3
 [0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/MadBomber/asgard/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/MadBomber/asgard/compare/v0.1.0...v0.1.1

data/CLAUDE.md

@@ -21,7 +21,9 @@ asgard quality
 asgard release
 ```
 
-Single test: `ruby -Ilib:test test/test_asgard.rb`
+Whole suite (one process, so SimpleCov sees everything): `ruby -Ilib:test -e 'Dir["test/test_*.rb"].each { |f| require File.expand_path(f) }'`
+
+Single file: `ruby -Ilib:test test/test_asgard.rb` (a single file alone will fall below the coverage minimum)
 
 ## Architecture
 
@@ -41,6 +43,10 @@ Single test: `ruby -Ilib:test test/test_asgard.rb`
 | `lib/asgard/base.rb` | DSL engine; inherits Thor, includes Shell |
 | `lib/asgard/shell.rb` | `sh` / `shebang` helpers |
 | `lib/asgard/tasks.rb` | `class Tasks < Asgard::Base` — the convention class users reopen; also holds gem-owned built-in tasks |
+| `lib/asgard/schedule.rb` | `Asgard::Schedule` — the `schedule` DSL registry; requires the files below |
+| `lib/asgard/schedule/declaration.rb` | Pure declaration validation + the backend API contract |
+| `lib/asgard/schedule/launchd.rb`, `systemd.rb` | Platform backends; shell out through an injectable runner |
+| `lib/asgard/schedule/commands.rb` | `asgard schedule ...` subcommands (registered as `_schedule`, mapped to `schedule`) |
 
 ### Naming Convention for Gem-Owned Methods
 
@@ -100,7 +106,7 @@ Asgard adds the following `module_function` methods to `Kernel`, making them ava
 
 ## Testing
 
-All tests are in `test/test_asgard.rb` (one file, ~11 named classes). SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
+Engine tests are in `test/test_asgard.rb`; scheduling tests are in `test/test_schedule.rb`, which uses a `FakeRunner` (records launchctl/systemctl argv) so both backends test on any platform. SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
 
 Key test patterns: tests frequently subclass `Asgard::Base` directly (not `Tasks`) to test the engine in isolation, and use `capture_io` for output assertions.
 

data/README.md

@@ -23,6 +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>Scheduled Tasks</strong> — run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code><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>
@@ -221,14 +222,28 @@ 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:
+`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-form) for the full explanation.
+See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-block-form) for the full explanation.
 
 ---
 
@@ -489,6 +504,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:
@@ -564,6 +606,39 @@ See [`examples/server_subcommands.loki`](examples/server_subcommands.loki) and [
 
 ---
 
+## Scheduled tasks
+
+Any task can run on a schedule under the platform's own scheduler:
+**launchd** on macOS, **systemd user timers** on Linux. Declare schedules at
+class level in `.loki`:
+
+```ruby
+class Tasks
+  schedule :daily_summary, at: "17:30", on: :weekdays
+  schedule :backup,        at: %w[02:00 14:00]          # on: defaults to :daily
+  schedule :sync,          every: 3600                  # seconds
+  schedule :report, options: "--period week", at: "16:00", on: :friday
+end
+```
+
+Then manage them with the built-in `schedule` command:
+
+```bash
+asgard schedule preview        # job files install would write
+asgard schedule install        # load declared entries; drop undeclared ones
+asgard schedule list           # installed entries, state, last exit status
+asgard schedule stop NAME      # stop one entry (persists across reboots and installs)
+asgard schedule start NAME     # start a stopped entry, or install just this one
+asgard schedule trigger NAME   # run an installed entry now
+asgard schedule log NAME [-f]  # print (or follow) the entry's log
+asgard schedule remove         # remove all of this project's entries
+```
+
+Jobs run `asgard <task> [options]` from the directory holding `.loki`, with
+the `PATH` captured at install time; a project `.envrc` is loaded at run time
+through `direnv exec`. See [Scheduled Tasks](https://madbomber.github.io/asgard/schedule/)
+for every keyword, entry naming, and file locations.
+
 ## `method_option` types reference
 
 | Type | CLI example | Ruby value |

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

@@ -27,6 +27,8 @@ abort "asgard: unknown command '#{argv.first}'" if argv.first&.start_with?("_")
 
 After loading task files, it calls `Tasks.validate_deps!` (circular dependency check) and `Tasks._reset_ran!` (clears per-invocation deduplication state) before starting Thor.
 
+If the dispatched task returns exactly `:fail`, `run!` exits with status 1 (the quality-gate convention). Any other return value, including `:warn` and `:skip`, exits 0.
+
 ---
 
 ## Kernel Methods
@@ -111,12 +113,12 @@ 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. 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). |
+| `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 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. |
@@ -175,12 +177,14 @@ 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.
+# 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-form) for the full explanation of the Proc form — why it exists, when it runs, and how errors are reported.
+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.
 
 ---
 
@@ -196,6 +200,8 @@ See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form) for t
 | `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`. |
+| `schedule` | class method (DSL) | `schedule :task, at:/every:, ...` — declares a scheduled entry. Extended from `Asgard::Schedule::DSL`; see [`Asgard::Schedule`](#asgardschedule). |
+| `_schedule` | subcommand | `asgard schedule SUBCOMMAND`, backed by `Asgard::Schedule::Commands`. `map "schedule" => :_schedule` keeps the typed name `schedule`, and a user task named `schedule` cannot shadow it. |
 
 ---
 
@@ -265,6 +271,22 @@ The warning is a shadowed ancestor `.loki` marker one directory further up the t
 
 ---
 
+## `Asgard::Schedule`
+
+Scheduled tasks. The user-facing guide is [Scheduled Tasks](schedule.md); this section covers the Ruby API.
+
+| Method | Signature | Description |
+|---|---|---|
+| `declare` | `Asgard::Schedule.declare(task, **settings) → Hash` | What `Tasks.schedule` calls. Validates via `normalize` and records the entry. Redeclaring an identical entry is a no-op; a different entry under the same name raises `ArgumentError`. |
+| `declarations` | `Asgard::Schedule.declarations → Hash` | Declared entries for this run, keyed by entry name. |
+| `normalize` | `Asgard::Schedule.normalize(task, options: nil, at: nil, on: :daily, every: nil, env: {}, as: nil) → Hash` | Validates one declaration and returns `{ name:, task:, args:, at:, on:, every:, env: }`. Pure. |
+| `backend_class` | `Asgard::Schedule.backend_class(platform = RUBY_PLATFORM)` | `Launchd` on darwin, `Systemd` on linux; raises `Asgard::Schedule::Error` elsewhere. |
+| `runner` / `runner=` | `Asgard::Schedule.runner → #call` | The command runner new backends use: `argv` in, `[output, success?]` out. Defaults to `RUNNER` (`Open3.capture2e`); tests assign a recording runner, and `nil` restores the default. |
+
+Both backends, `Asgard::Schedule::Launchd` and `Asgard::Schedule::Systemd`, implement the same instance API: `files`, `install`, `uninstall`, `start`, `stop`, `trigger`, `installed_names`, `status`, `log_path`, `notes`. Each class also exposes the pure helpers that build its job files (`Launchd.plist`, `Systemd.service_unit`, `Systemd.timer_unit`, ...), so they can be tested without a scheduler.
+
+---
+
 ## `Asgard::Base` Internal Class Methods
 
 These are implementation details exposed for extensibility. Prefer the DSL methods above in normal use.
@@ -296,6 +318,7 @@ These are implementation details exposed for extensibility. Prefer the DSL metho
 | Class | Superclass | Description |
 |---|---|---|
 | `Asgard::Error` | `StandardError` | Base error class for all Asgard errors. |
+| `Asgard::Schedule::Error` | `Asgard::Error` | Raised when a `launchctl`/`systemctl` command fails, or on an unsupported platform. `run!` reports it as `asgard: <message>`. |
 | `Asgard::CircularDependencyError` | `Asgard::Error` | Raised by `validate_deps!` when a cycle is detected in the dependency graph. `run!` catches this and calls `abort` with a clean message. |
 
 ```ruby

data/docs/changelog.md

@@ -1,132 +1 @@
-# Changelog
-
-All notable changes to Asgard are documented here.
-
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asgard adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [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
-
-### Changed
-
-- `*.loki` files are no longer auto-loaded by default. Pass `--auto-load` to `asgard` to load all `*.loki` files from the project root alphabetically before `.loki`. This is a breaking change for projects using the multi-file layout.
-- Added `--auto-load` as a built-in CLI flag in `Tasks`, visible in `asgard help`
-
----
-
-## [0.1.2] — 2026-05-29
-
-### Added
-
-- `--version` built-in CLI flag — prints `Asgard::VERSION` and exits; implemented as a `_`-prefixed method in `Tasks` per the gem-owned naming convention
-- `--debug` and `--verbose` built-in `class_option` declarations on `Tasks` — set `$DEBUG`/`$VERBOSE` before any task runs via the `invoke_command` hook in `Asgard::Base`
-- `debug?` and `verbose?` private predicate helpers on `Tasks` — thin wrappers around `$DEBUG` and `$VERBOSE` for use inside task bodies
-- `_` prefix convention for gem-owned methods in `Tasks` — built-in methods use `_` prefix to distinguish them from user-defined tasks
-- `run!` guards against direct invocation of `_`-prefixed commands with a clean error message and exit 1
-- `examples/` directory with working `.loki` files:
-  - `kitchen_sink.loki` — demonstrates the full Thor DSL (all option types, `long_desc`, `class_option`, `default_task`, `map`, `depends_on`, `var`, `no_commands`, `private`)
-  - `server_subcommands.loki` — subcommand group for server management
-  - `db_subcommands.loki` — subcommand group for database management with `depends_on` chaining
-  - `concurrent.loki` — demonstrates parallel task execution with interleaved thread output
-- README sections: Helper methods, Subcommands, Thor wrapper callout
-
-### Fixed
-
-- Replaced `warn`/`exit 1` with `abort` throughout `run!` — `Kernel#warn` is silenced when `$VERBOSE = nil`, which is the default in Ruby 4.0; `abort` writes to `$stderr` regardless
-
-### Changed
-
-- `--debug` and `--verbose` promoted from mapped tasks to `class_option` — they now work as modifiers alongside other commands (e.g. `asgard build --debug`) rather than as standalone commands
-- Removed all references to `just` task runner and `recipe` terminology; Asgard uses "task" throughout
-- `depends_on` parameter renamed from `*recipes` to `*tasks` for consistency
-
----
-
-## [0.1.1] — 2026-05-28
-
-### Added
-
-- Parallel dependency execution — wrap deps in an array to run them concurrently:
-  `depends_on [:build, :lint]` or `depends_on :setup, [:build, :lint], :deploy`
-- `Asgard.run!(argv)` — single entry point encapsulating find, load, validate, and start
-- `Asgard.load_loki(dir)` — auto-loads all `*.loki` files in a directory alphabetically
-- `Tasks` class pre-defined by the gem (`class Tasks < Asgard::Base`) — task files reopen it without restating the superclass
-- `lib/asgard/tasks.rb` — ships the pre-defined `Tasks` class
-
-### Changed
-
-- Replaced `SimpleFlow` dependency with `Dagwood` — purpose-built DAG library with no extra dependencies and no Ruby 4 compatibility issues
-- `bin/asgard` simplified to two lines: `require "asgard"` + `Asgard.run!(ARGV)`
-- Task file convention: `.loki` is the project root marker and entry point; `*.loki` files each reopen `class Tasks` and are auto-loaded before `.loki`
-- `Asgard.find_task_files` renamed to `Asgard.find_task_file` (singular — only `.loki` is the entry point)
-- `depends_on` now accepts mixed sequential/parallel stages; bare symbols run sequentially, arrays within the splat run in parallel
-- `run!` handles its own errors — missing `.loki` and circular dependencies produce a clean one-line message and exit 1 rather than a backtrace
-- Thread-safe dep deduplication via class-level `_ran_tasks` Set + Mutex replaces Thor's `@_invocations`
-- Removed `import` macro — task files use Ruby class reopening instead of modules
-
-### Removed
-
-- `SimpleFlow` dependency (replaced by `Dagwood`)
-- `logger` gem workaround (was only needed for SimpleFlow on Ruby 4)
-- `*.loki` glob fallback in `find_task_file` — only `.loki` is the auto-discovered entry point
-
----
-
-## [0.1.0] — 2026-05-28
-
-### Added
-
-- `Asgard::Base` — Thor subclass providing the task DSL
-- `depends_on` — declare task dependencies; dependencies run at most once per invocation
-- `var` — declare static or lazy-evaluated variables available to all tasks
-- `import` — flat-merge a task module into the current class
-- `dotenv` — load a `.env` file into the environment
-- `sh` — run a shell command or multiline heredoc script; exits with the command's status on failure
-- `shebang` — write a script body to a tempfile and execute it with a given interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`, or any custom interpreter)
-- `Asgard.find_task_files` — search current directory and ancestors for task files
-- Task file resolution: `.loki` takes priority; falls back to all `*.loki` files sorted alphabetically
-- `asgard` executable — finds task files, validates dependency graph, dispatches via Thor
-- Circular dependency detection via `SimpleFlow::DependencyGraph` at startup
-- 100% test coverage enforced via SimpleCov (95% minimum threshold)
-- Quality task in `.loki` runs flog after tests
-
-[Unreleased]: https://github.com/MadBomber/asgard/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0
-[0.1.2]: https://github.com/MadBomber/asgard/compare/v0.1.1...v0.1.2
-[0.1.1]: https://github.com/MadBomber/asgard/compare/v0.1.0...v0.1.1
-[0.1.0]: https://github.com/MadBomber/asgard/releases/tag/v0.1.0
+--8<-- "CHANGELOG.md"