ADR-511: Every mutating lifecycle verb reports what it would change until --commit¶
Summary¶
- Decided: every
ways manageverb that changes the install prints what it would change and changes nothing until--commitis given. The report has one shape for every verb: a title, sections under ruled headers, a mark per line (↑ moves, = unchanged, + added, * fixed, → an action, ⚠ needs attention), coloured by role on a terminal and plain in a pipe.updatereports versions, release notes, the source delta, local changes, the actions and dev links. A commit run prints one header per stage with ✓, ⚠ or ✗ per outcome and keeps raw command output for--verboseor a failure.--yesand--dry-runstay accepted.install.manage_mode: commitlets an operator restore apply-by-default forupdate,repairandtarget. The hiddenreconcilekeeps applying, and the installer keeps installing in one step. - Trades away: every caller that means to apply must now say
--commit: scripts, skills, hints, the settings screens and the operator's habit. An operator who typesways manage updateand walks away has updated nothing. - One-way? No: reversible. The default is one function and one setting; flipping it back is a one-line change, and
install.manage_mode: commitdoes it per machine today. - Probes: Confident (default): you want a bare
ways manage updateto change nothing on disk except a fetch, and to tell you what--commitwould do. Not confident (scope): you wantrepairandtargetto follow the same default, so thatways manage repairon its own reports, even though a repair is usually run to fix something now. - Inversion: one end keeps every verb applying at once and adds a richer
--dry-run, so habits and callers stay as they are and the operator has to remember to look first. The other end makes every lifecycle path report first with no way to opt out, including the installer one-liner and the updater's cross-release call. This decision reports first for every verb a person types, keeps one setting to opt out, and leaves the two calls that come from another release, or that are themselves the explicit request, applying.
Context¶
The install changes in several places at once: the app checkout, six suite binaries and way-embed, the corpus, each target's projection and settings.json, the attend mod, and the PATH links. A contributor's make dev-install adds a seventh: links that point into a checkout other than the app. Before this decision the update applied on a bare invocation, and its scroll was the raw output of git, make, the download script and cargo. Its --dry-run printed a fixed list of steps, the same on every machine, that named no version, no commit and no release note.
The operator asked for the update to report before it acts: what each component moves to, the release notes in between, and the delta since the last update, with colour and visual breaks in place of the raw scroll. The operator then asked for the other lifecycle flows to follow the same convention.
Some verbs already had half of it. uninstall and reinstall print a plan without --yes (ADR-198, ADR-509 §3), target add takes --dry-run, and target plan previews activation (ADR-184). repair, target enable|disable|remove and update applied at once.
Two callers cannot pass a new flag. The previous release's updater spawns reconcile on the newly installed binary (ADR-509 §4), and scripts/install.sh runs bin/ways reconcile on a binary that make setup may have downloaded from an older release.
Decision¶
- What-if is the default. A mutating
ways manageverb without--commitchanges nothing except a read-only fetch, and prints what it would change. The verbs areupdate,repair,target add|enable|disable|remove,uninstallandreinstall. A what-if exits 0 even when it found something to change: a script that runs it underset -emust not fail on the report. - One apply flag.
--commitapplies, on every verb.--what-ifnames the default explicitly.--yes(fromuninstallandreinstall) and--dry-run(fromupdate,repairandtarget add) stay accepted on every verb as hidden aliases of--commitand--what-if, so existing docs and habits keep working. The two flags conflict. - One setting.
install.manage_modein the user config takeswhatif(the default) orcommit. Withcommit,update,repairandtargetapply without the flag; a flag on the command line wins over the setting.uninstallandreinstallremove the install and always need--commit.ways settingslists the key on the install tab. - One report. The report and the step scroll live in one module of the
waysbinary (cmd/lifecycle.rs) that every verb uses. They draw from the theme engine's roles (ADR-504): a ruled header per section, a mark and role per line, the terminal palette on a terminal and plain text in a pipe, underNO_COLOR, or withTERM=dumb. The plain text is the coloured text with the escapes removed. A commit run prints one header per stage and ✓, ⚠ or ✗ per outcome. The output of the commands it runs is captured, shown when a command fails, and streamed under--verbose. - Versions and notes where a verb moves versions.
updatereports, for each suite binary, way-embed and the attend mod, the version installed and the version at the target. For each component that moves it prints the GitHub release notes of every<component>-vX.Y.Zrelease after the installed version up to the target, without the heading and without the CI tail after the closing---. The notes come from the GitHub Releases API throughcurl, the tool the installer one-liner already needs, with a token fromGH_TOKENorGITHUB_TOKENwhen set.ghis not required. Unreachable notes are named as unreachable, and the report goes on.WAYS_RELEASES_JSONnames a file to read in place of the API, for a mirror or a test. - The source delta.
updatefetches the app checkout and summarisesHEAD..<target>: a count per area (the component a conventional scope names, else the area most of the commit's paths fall in), the feats and fixes listed, the rest counted, and the merged pull requests.--verboselists every commit. It also lists local changes the pull's autostash would carry, and the actions--commitwould take on this machine. - Dev links are detected. A verb that relinks binaries reads each suite binary's link in
$XDG_BIN_HOME(else~/.local/bin) and in each enabled target'sbin/. A link whose target lies outside the app and inside a git checkout is a dev link. The report names each one, says the verb would point it back at the app, and namesmake dev-installas the way back. - Calls from another release keep applying.
ways reconcile, the hidden fixed name of ADR-509 §4, applies with no flag, as before, and takes--what-if/--dry-runto report. The previous release's updater and the installer call it, and neither can pass a flag the binary it calls may lack. Everything a person reads namesways manage repair --commit. - The installer is the explicit request.
curl … | bashandscripts/install.shinstall in one step: running the one-liner is the request to apply, and a what-if there would leave a fresh machine with nothing. It prints the same staged report in shell, with the same headers, marks and plain fallback, since nowaysbinary exists when it starts. The installer callsreconcile, so item 8 keeps it working with any binary. - Make targets are out of scope.
make dev-install,make dev-restoreandmake purge-attend-stateare contributor and recovery tools whose interface is make's: a target does its work, andmake -npreviews it. attend has no lifecycle verb of its own; its binaries, its mod and its state are installed, updated and removed throughways manage, so it follows this convention through them. - Internal callers say
--commit. The Makefile'supdatetarget, the ways-update skill, the settings screens' actions, hints that tell the operator to run a verb, and the tests that apply pass--commit. In-process callers (the updater's reproject,reinstall's repair,uninstall's withdrawal) call the apply path directly.
A what-if of ways manage update, one release behind (trimmed):
ways manage update: what-if
app ~/.local/share/agent-ways · at d3fe7f7d · target 17b500e0
── Versions ────────────────────────────────────────────────────
↑ ways 1.41.0 → 1.41.1
= ways-audit 1.0.3 unchanged
↑ attend mod 0.28.0 → 0.28.1
── Release notes ───────────────────────────────────────────────
ways 1.41.0 → 1.41.1
ways-v1.41.1
### Fixed
- **Entry dialogs wrap a long error.** … (#1021).
── Changes ─────────────────────────────────────────────────────
23 commits, 6 pull requests merged
attend (4 fix, 2 docs, 1 release)
fix fix(attend): a session with no turn yet is wakeable
── Actions ─────────────────────────────────────────────────────
→ pull: fast-forward d3fe7f7d → 17b500e0 (origin/main)
→ ways: download the ways-v1.41.1 release
→ reproject ~/.claude (ways manage repair)
· Nothing changed. Run `ways manage update --commit` to apply.
This amends ADR-150's Decision (the self-update applies only under --commit, and reports first), ADR-144's Decision (the repair verb reports first; the reconciler's own entry, reconcile, still applies), ADR-184's Decision (target add|enable|disable|remove report first; target plan is unchanged), and ADR-509's Decision (item 1's table: every verb takes --commit; item 3's --yes becomes an alias of --commit; item 5's one-release aliases ways update, ways uninstall and ways target report like the verbs they forward to).
Consequences¶
Positive¶
- An operator sees what an update would do, and why, before anything moves: versions, notes, commits, local changes, actions and dev links in one page.
- A contributor with
make dev-installactive is told that an update or a repair would undo it, before it does. - The step scroll reads as stages with outcomes, and the raw output is still there for a failure or
--verbose. - One module holds the report and the scroll, so a new verb takes the convention by using it.
Negative¶
- Every applying caller changes: docs, skills, hints, the settings screens, tests and habits. A caller left on the bare form silently reports instead of applying. The call-site test checks two ways. In Rust, shell, Makefiles and the TypeScript mod it fails a
ways manage <verb>without--committhat follows a cue word such as "run" or "then", or that the settings screens queue; a hint with no cue word still gets past it. In the docs, skills and ways it fails every bare mutating verb unless its form makes it a description (a heading, a fenced command whose comment says it only reports, a describing verb right after it, or a word such as "whether" or "as" right before it) or it is on an allowlist with its reason; an instruction written in one of those forms still gets past it. - The release notes need the network and an unauthenticated API call per page of 100 releases, against GitHub's limit of 60 an hour per address.
ways manage repairrun to fix something now needs--commit; the operator who wants the old behaviour setsinstall.manage_mode: commit.reconcileandmanage repairnow differ in their default, which a reader of the source has to keep apart.
Neutral¶
install.manage_modeis user scope only. A target's or a project's file cannot make a verb apply.- The exit code of a what-if does not say whether an update is available. A script that needs to know can compare versions itself; a distinct code would break
set -ecallers.
Alternatives Considered¶
- Keep applying by default and enrich
--dry-run. Rejected: the operator asked for the default to be the report, and a richer flag that has to be remembered is what the old--dry-runalready was. - Report first on
updateonly. Rejected after the operator's second message: the verbs share one install, and a convention that holds for one verb teaches nothing about the others. - Make
reconcilereport first too. Rejected: the previous release's updater and the installer call it with no flag, so every update from the previous release and every fresh install would stop projecting. - Read the notes with
gh. Rejected:ghis optional on an install, and its absence would hide the notes on exactly the machines without a toolchain.curlis already required by the one-liner. - A distinct exit code when an update is available. Rejected for now (see Neutral).