spectral/ROADMAP.md

# Roadmap

Where spectral is heading. Nothing here has a date attached. The order is
roughly the order the work is worth doing, and the distance between items
ranges from one afternoon to a design conversation first.

## Now

Done. Every verb runs, and the loop closes end to end: a commit went from a
working tree to a `git send-email` plan, then round again as v2 threaded off
the original. `README.md` has the walkthrough and the acceptance evidence.

The milestone was this:

```text
quest -> edit -> check -> format -> commit -> create -> submit -> v2
```

One patch through one review cycle without dropping to a shell to run git or
checkpatch by hand. The one step that stays yours on purpose is `git add`:
`patch commit` commits what you staged, because sweeping a dirty tree into a
kernel patch is a review comment nobody asked for.

The two tests this section named are in place: the `vN-` naming rule in
`reroll_path`, and the `To:`/`Cc:` split in `lookup`, the second of which is
also asserted against the host's real `get_maintainer.pl` in an opt-in test.

`rg -n 'todo!' src/` finds nothing. What is left overall is the three gaps in
the README's *What is not proven*, and `Later` and `Far` below.

## Next

All three landed, in this order. The sections below say what each one does now.

### A series instead of a single patch

Done. `patch create xhci-port-rearm --range master..HEAD --cover-letter
"<blurb>"` writes a numbered set through `git format-patch`, cover letter
included; `patch submit` takes a directory or several files and sends them in
one `git send-email` invocation; `patch update <dir>` re-rolls the whole set
through `--reroll-count`, so every file moves to vN together, and the
superseded files go only once the new revision is complete. The blurb's first
line becomes the cover letter's subject, and leaving `--cover-letter` off
leaves git's template in place, which `git send-email` refuses.

A `series.toml` in the directory records the range it was generated for: both
ends as hashes, the revision, the files, and the blurb. The range is what makes
a re-roll safe, since regenerating `base..HEAD` instead would quietly pick up
every commit that landed on the branch since `create` and mail it with the set.

### spectral doctor

Done. It checks, in the order a first run hits them: the tree path and where it
came from, that the path is a kernel tree, `scripts/checkpatch.pl`,
`scripts/get_maintainer.pl`, `MAINTAINERS`, git, `git send-email`, a sender
identity, whether any mail route is configured, qemu on `$PATH`, that the patch
directory is writable, and whether a config file exists.

One line per check with the fix under it, and the summary names the first hard
failure. Exit 1 when something hard failed; a missing qemu or a missing mail
route warns and keeps exit 0, because `--dry-run` is where the loop actually
stops on this machine.

### Config file and init

Done. `~/.config/spectral/config.toml` (or `$XDG_CONFIG_HOME`), holding the
tree path, the patch directory, always-CC addresses and a send-email identity.
Precedence is the environment over the file over the built-in default, and
`$SPECTRAL_PATCH_DIR` joined `$SPECTRAL_KERNEL` for symmetry.

`spectral init --tree <path>` verifies a tree, or `--clone <url> [--depth N]`
fetches one, then writes the config. A second run with the same tree says so
and writes nothing; a run that would change an existing answer is refused until
`--force`. Malformed TOML, an unknown key and a relative path are named errors
rather than surprises three commands later.

## Later

### More quest sources

`QuestSource` exists so this costs one impl per source. Candidates, roughly
in order of how useful they look: syzbot, the kernel-janitors TODO list, and
lore.kernel.org threads marked as needing work.

Worth doing at the same time: remembering what quest has already shown you. A
random picker that keeps handing back the same bug is worse than no picker.

### More checks

`patch check` runs checkpatch today. The kernel holds more opinions than
that, and each of these is a flag on the existing verb rather than a new one:
sparse through `make C=1`, `make W=1` for the extra warnings, and
`dt_binding_check` for device tree patches.

`kernel test` could grow kselftests and a syzkaller run, which answer a
different question from "did it boot".

### Review tracking

Submitting is half the loop. The other half is waiting, and spectral has
nothing to say about it today. A `spectral patch status` could read the
thread for a patch you sent, report the tags it found (`Reviewed-by:`,
`Tested-by:`, `Acked-by:`), and let `patch update` fold them in when you
re-roll.

That needs spectral to record what it sent and where, which nothing does
today. Where that state lives is the design question to settle before the
feature. A series already carries `series.toml`, which is the smallest version
of that record: it is what a re-roll reads.

### Packaging and polish

- shell completions through `clap_complete`, and a man page through
  `clap_mangen`, once the command surface stops moving
- the three gates from the README wired into CI, so they stop being
  something a contributor has to remember
- release packaging: crates.io, plus an AUR package for the Arch systems
  this has been developed on

## Far

Both of these are front ends over verbs that do not exist yet, so neither is
worth starting before `Now` and most of `Next` are done. They are listed so
the intent is on record before anyone starts building either one.

### A TUI

A session view over the same verbs, for the loop rather than for one command
at a time. The panes that matter:

- the issue you are working on, from `kernel quest`, with its URL
- the tree: branch, dirty files, and what checkpatch reports
- the patch files on disk and which revision each one is at
- the recipients for the selected patch, so you see who is being mailed
  before you send rather than after
- the qemu serial console, streaming, while `kernel test` runs

The constraint that keeps it honest: the TUI calls the same functions the
verbs call. Nothing is implemented twice, and every action in it stays
available as a typed command. `src/cli.rs` and the rule that command modules
return what they produced are what make that possible.

The cost is that the verbs block. `git`, `checkpatch.pl`, `make`, and qemu
all run synchronously to completion, and a TUI cannot block its render loop.
The work has to move onto background tasks that report progress back through
a channel, which means the command modules need a progress story they do not
have today. That is the actual work in the TUI, and it is why the TUI comes
after the verbs rather than alongside them.

`ratatui` is the obvious crate for it.

### spectral auto

This automates the mechanical part of the loop, not the judgment. Deciding
what to fix and writing the fix are yours. Running checkpatch twice, creating
the patch, and looking up maintainers are not.

So `auto` walks the chain to a halt point and stops there:

```console
$ spectral auto                   # dirty tree to a patch that is ready to send
$ spectral auto --stop-at create  # or stop earlier
```

It never sends mail unless told to. Submitting to a mailing list is the one
step that rerunning a command cannot undo, so `auto` stops one step short by
default and shows the recipients and the command line, the same way `patch
submit --dry-run` does.

Once review tracking lands, `auto` picks up the more useful half of its job:
find the thread for the patch you sent, collect the tags, re-roll to vN,
recompute the recipients, then stop at the same place. That is most of what a
v2 cycle consists of.

It has to be idempotent. Running it twice on a tree that has not changed
should not produce a v3. `reroll_path` is already specified as a no-op at the
same revision, and `auto` inherits that requirement.

It depends on the verbs, on `doctor` to fail fast instead of halfway, and on
the config and state files the sections above describe. `doctor` and the config
file are here now; the state file is what review tracking still has to decide.

## Not planned

- Reimplementing checkpatch.pl or get_maintainer.pl, or shipping copies of
  them. They come from your tree on purpose, so spectral cannot end up
  disagreeing with the kernel about style or maintainers.
- Managing your tree's remotes, branches, or rebases. spectral reads git
  state; it does not take the repository over.
- A GUI or a web UI. The TUI in `Far` is a front end over the same verbs, and
  anything it can do stays reachable by typing the command yourself. A
  graphical app would mean building those verbs a second time.
- Answering review mail for you. Reporting the tags in a thread is useful;
  writing replies in your name is not.