Inspecting Plans and explaining generated changes
Use the validated Plan views to review required outputs, producer instructions, artifact dependencies and publication routes before executing a Run. These read-only views explain the complete generated Plan and its changes. They do not observe output bytes, verify a release, or authorize execution.
The Plan in .github/nvkr-run/plan.json remains canonical, compact JSON. Its exact bytes still participate
in Plan identity and generated-file drift checks. Keep human views outside .github/nvkr-run/: that directory
admits only manifest-owned generated files. Inspection never updates the Plan or its ownership manifest.
Read the Plan
Inspect the current generated Plan without resolving catalogs or contacting an external service:
The text view lists required output slots and Build Digests, every producer instruction and dependency,
and each stored producer field in sorted order. This includes source and vendor pins, patch order, environment
values, build/prepare argv, Nix flake inputs, Packer/material inputs and artifact paths when present. It also
lists artifact operations and publication routes. Nonprinting characters are escaped for display. --pretty shows every stored field as indented JSON; it is a display view and is rejected as a
canonical Plan input. --json emits the exact canonical Plan bytes, with no appended newline.
The same views can compile authored inputs directly:
Use either --plan or the pair --definition and --environment. Compilation can need access to pinned
Git objects for catalog pin-set revalidation. Reading an existing generated Plan needs only its file.
Readers require the current schema, canonical bytes, safe bounded regular files, and complete graph and
binding validation. Invalid input produces a coded error before any result bytes are emitted.
Browse in the terminal
The explicit terminal explorer uses validated typed output/operation membership
and dependencies. It leaves the Plan and generated ownership manifest unchanged.
Use arrows to select, Enter for details/dependencies, Tab or 1/2 for panes, Esc to go back,
/ for output search, f for filters and ? for help. Tabs identify Outputs
and Details, with frames separating the panes. Activity appears only when supplied
(for example, during live Runs); static Plans have no Activity tab. a selects
the Activity pane only when available. q asks before closing
this read-only view: y or Ctrl+C closes it; n, Esc or Enter keeps it open. Closure does not
execute a Plan or clean up a Run. Small terminals use a single pane.
--no-color and nonempty NO_COLOR preserve textual state and focus.
The default Plan output remains plain; --json retains byte-exact canonical
output and --pretty retains its display-only JSON format. Explicit terminal mode
requires usable interactive stdin/stdout and cannot be combined with JSON/pretty
output. Planned operations and declared evidence lanes are descriptions, not
observed artifacts or authenticated runtime/release claims. For recorded attempts
and live Run presentation, see Lifecycle.
Follow linked graphs
The default --view complete includes every embedded producer IR node, factory operation, intermediate
artifact, required output slot and publication route. Exact producer references join the instruction graph
to the artifact operation graph. This exposes chart/image packaging dependencies, SBOM and evidence flow,
release preparation, publication, signing and verification where the selected Plan contains them.
The focused views keep exact Plan references. The complete view joins them through edges labeled
instruction. A requires edge goes from an upstream producer to its consumer; produces and consumed by
connect factory operations through artifacts. fulfills slot links an artifact to its independently required
named output. publication route describes the selected transport destination. These are different
relationships; a route or a planned verification node is not evidence that publication or verification ran.
Mermaid labels use numeric entity escaping,
DOT labels use DOT quoting for quotes, backslashes and line breaks; other nonprinting characters are shown
as literal Unicode escape text. Renderer node IDs are generated independently of input strings.
JSON preserves complete vertex keys, source references and labeled edges under
nvkr.dev/plan-graph-view/v1. Its planDigest names the validated source Plan; authority: description-only
does not grant a new identity or execution receipt. DOT can be rendered with Graphviz; Mermaid can be
embedded in documentation viewers that support it. Large Plans can produce large diagrams; use a focused
view to reduce visual load without dropping nodes from that chosen graph.
These graphs describe planned dependencies. Registry navigation cannot recover an absent executable Plan from a publication root or infer producer edges from matching artifact names.
Compare regenerated Plans
Save the previous exact Plan before regeneration, then compare it to the regenerated file:
The root regeneration uses the committed M2 inputs and the generator identity described in the M2 instructions. Generate alternative Definitions into scratch roots as shown in the pipeline guide.
The default text report identifies changed, added or removed per-output Build Digests, counts every changed
field by category, and shows changes in shared authored inputs, provider tools and publication routes.
Repeated catalog snapshots, derived identities and generated references remain counted; --details prints
every changed path. --details is valid only with text output; combining it with --format json fails
before Plan input is read. Long text values are explicitly abbreviated at a UTF-8 boundary. The canonical
descriptive JSON report retains every complete before/after value, including added and removed objects.
Named schema collections are matched by their keys, so inserting an output does not present every later
output as replaced. Paths use JSON Pointer escaping plus selectors such as /builds/@name=cwe and
/graph/nodes/@id=package~1cwe. Text paths use Go string quoting to escape control characters; JSON retains
the exact paths. Ordered arrays, including command arguments and patches, remain positional.
A changed ordering among surviving named entries is reported as @order. Generated IDs that change with
pins appear as removed and added references; no heuristic guesses that two different producer identities
are interchangeable. JSON numbers retain integer precision.
A difference is a successful descriptive result by default. Add --exit-code for exit status 3
(NVKR-E-DIFF) when the two Plans differ. Malformed Plans and unsupported view options remain ordinary
coded errors. A text summary is not a substitute for run generate --check: semantic comparison explains
two already generated Plans, while the drift gate regenerates all owned files from authored inputs and
checks their exact bytes. Workflow-only changes still require reviewing the generated workflow diff.
Implementation and evidence
pkg/nvkr/planview owns validated snapshots, display projections and comparisons. The CLI only selects inputs
and formats. The module reuses factory-owned canonical loading and full Plan validation; it grants no
artifact or execution authority. The Plan schema, canonical codec, typed digest families and generated
bundle format are unchanged.
Contract tests cover exact-byte JSON, display-only pretty JSON, caller-mutation isolation, invalid complete Plans, bounded/no-follow file loading, complete graph vertices and edges including the maintained controller chart/CWE relationship, diagram escaping, stable named comparisons, ordered argv/patches, large integers, absent-versus-null values, and transport/execution changes that preserve Build Digests. CLI tests cover file views, graph formats, concise/full differences, exit status and failure before output. These contracts live in the Plan-view tests and the CLI inspection tests. This is local inspection/contract evidence; it adds no registry, runner, signing or OS execution acceptance.