Planning changes

Inspect changes, deferred conditions and conflicts before executing actions.

Run from a consumer repository, or supply its root:

./etch plan --repo examples/minimal --profile developer
./etch plan --repo examples/minimal git --verbose

As with doctor, choose either a profile or explicit module names. With neither, Etch selects every discovered module in lexical order. Profile order is retained where dependencies permit. Required modules must be selected explicitly.

The default output groups selected modules, proposed CHANGE, RUN, or SKIP actions within each module, and a short count summary. Conditional skips and deferred work remain visible with their reasons. Use --verbose for dependency order and action IDs, and to inspect current provider observations, job limits, resource capacities, refresh points, network and elevation declarations, ownership claims, facts, and provider origins. Opaque actions may do more than Etch can predict.

Status words carry the meaning in both terminal and plain-text output. Etch colors them only in an interactive terminal; NO_COLOR disables color.

Planning returns zero for a valid snapshot, including valid deferred work. Invalid configuration, provider errors, unresolved required facts, missing hard dependencies, cycles and ownership conflicts return one. Once inspection starts, the report collects independent failures and shows ERROR entries with reasons alongside the changes it could inspect. Grouped link and create actions inspect every configured destination before reporting blocked paths. Fix the reported issues, then run a follow-up plan before applying.

If dependency checks cannot complete, the report says so and retains available inspection results; it cannot promise a complete execution order or validate provider-derived metadata for actions whose inspection failed. Configuration or plugin-loading failures can prevent planning from starting and are reported on stderr. Missing soft after targets produce warnings. Doctor includes these current-plan errors alongside all selected declarations and fact probes. Apply still requires a valid snapshot before executing actions.

What inspection means

Planning calls provider validation, inspection and planning methods. It never calls an action provider’s apply, downloads an installer, or executes a shell/script action. Core inspection reads paths, environment variables and command presence. Requested version facts may run their bounded argv probes. Choose version probes that only inspect the system. Their configured commands are executable code.

Declared plugins are trusted Python, including import-time code and inspection methods; planning does not sandbox them. A provider must honor the read-only inspection contract. No elevation is granted by planning. A plan can report requested elevation; only apply with --allow-sudo authorizes a declared request.

The report prints requested fact values, so avoid sharing output containing private environment facts. Provider payloads and command environment dictionaries are not printed. Plans describe known executables but cannot predict arbitrary script effects. For opaque commands, a missing network declaration is reported as unknown.

Deferred work

An unavailable named fact initially leaves its condition unresolved. The planner inspects enabled actions and builds a dependency graph, then checks whether an eligible earlier action refreshes that fact. A producer must be enabled, propose actual work, and have only enabled ancestors. A skipped, self, later or unrelated producer cannot justify deferral. Unresolved conditions without that evidence fail.

For example, an installer action with "refresh": ["tool_version"] can precede an action gated by "when": {"fact": {"name": "tool_version", "matches": ">=1"}}. If the tool is absent, the second action is shown as deferred without inspecting its provider or claiming its destinations. The installer is not downloaded.

This is a snapshot of current observations. Refresh entries describe future work; planning neither invalidates nor regathers facts after proposed changes. Deferred actions need new condition evaluation, provider inspection, dependency validation and ownership checks after the producer succeeds. The staged executor performs those checks during apply. The existing graph rules withhold dependencies attached to inactive/deferred gates; declaring a dependency on an unresolved action does not by itself prove an earlier producer.

Use --timings to measure provider checks without executing actions. It can be combined with --verbose; see CLI output options.