Add agent-friendly JSON workflow validation

CHANGELOG.md

@@ -8,6 +8,9 @@ follow [Semantic Versioning](https://semver.org/) after the initial development
 
 ### Changed
 
+- Standardized opt-in machine output on the versioned `electrace.cli.v1` success and
+  error envelope, including parse-time CLI failures and stable exit semantics; the
+  Typer minimum is now 0.20, the oldest validated release for this command surface.
 - Published the source under the BSD 3-Clause License with clean public package and
   citation metadata.
 - Consolidated the distribution, Python package, command, configuration filename,
@@ -50,6 +53,8 @@ follow [Semantic Versioning](https://semver.org/) after the initial development
 
 ### Added
 
+- Added strictly read-only `electrace workflow validate --json` planning for resolved
+  frames, commands, inputs, outputs, dependencies, scheduler settings, and warnings.
 - Added a compact coding-agent guide and installable ElecTrace skill for routing
   existing-output analysis and approval-gated local or Slurm workflows through the
   public CLI.

CITATION.cff

@@ -7,7 +7,7 @@ type: software
 authors:
   - family-names: Ellis
     given-names: Austin
-version: 0.1.0a3
+version: 0.1.0a4
 license: BSD-3-Clause
 abstract: >-
   ElecTrace is a research-software framework for tracking electronic-topology

README.md

@@ -78,9 +78,14 @@ Create the manifest, edit it for the calculation, and stage the selected frames:
 electrace workflow init electrace-workflow.yaml \
   --images /absolute/path/to/neb-images
 # Set executable paths, templates, frames, and scheduler settings in the YAML.
+electrace workflow validate electrace-workflow.yaml --json
 electrace workflow stage electrace-workflow.yaml
 ```
 
+Validation resolves the selected frames, commands, inputs, outputs, dependencies, and
+scheduler settings without creating a workspace. Commands also accept `--json` for a
+common `electrace.cli.v1` response envelope suitable for scripts and coding agents.
+
 Run locally and analyze the collected outputs:
 
 ```bash

docs/agents.md

@@ -19,8 +19,8 @@ electrace doctor --json
 The built-in demo requires no external scientific program:
 
 ```bash
-electrace demo --output .electrace-demo
-electrace inspect .electrace-demo/electrace-results
+electrace demo --output .electrace-demo --json
+electrace inspect .electrace-demo/electrace-results --json
 ```
 
 ## Install the Codex skill
@@ -51,10 +51,22 @@ electrace --help
 electrace doctor --json
 ```
 
+Every operational subcommand accepts `--json`. Successful and handled-error responses
+use one compact, unstyled `electrace.cli.v1` document with the fields `schema_version`,
+`ok`, `command`, `data` or `error`, `warnings`, and `artifacts`. Help and version output
+remain human-readable; request them without `--json`. Exit code `0` means the operation
+succeeded, `1` means a completed benchmark or external execution reported failure, and
+`2` means the request or a prerequisite was invalid. The public contract is the
+[`electrace.cli.v1` schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.cli.v1.schema.json).
+Resolved workflow plans in `data` follow
+[`electrace.workflow-validation.v1`](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.workflow-validation.v1.schema.json).
+
 If supported descriptor results already exist, it should create and review
-`electrace.toml`, run `electrace analyze`, and consume `analysis.json` as the canonical
-result. If calculations are missing, it should create and review
-`electrace-workflow.yaml`, stage the selected frames, and inspect workflow status.
+`electrace.toml`, run `electrace analyze --json`, and consume `analysis.json` as the
+canonical result. If calculations are missing, it should create and review
+`electrace-workflow.yaml`, run
+`electrace workflow validate electrace-workflow.yaml --json`, then stage the selected
+frames and inspect workflow status with `--json`.
 Local execution and Slurm submission remain explicit actions; the skill does not add
 `--yes` unless the user authorizes the reviewed job scope.
 

docs/index.md

@@ -27,6 +27,8 @@ capabilities from planned or scientifically unvalidated work.
 - [Plugin protocol v1](spec/plugin-protocol-v1.md)
 - [`electrace.features.v1` JSON Schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.features.v1.schema.json)
 - [`electrace.workflow.v1` JSON Schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.workflow.v1.schema.json)
+- [`electrace.cli.v1` JSON Schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.cli.v1.schema.json)
+- [`electrace.workflow-validation.v1` JSON Schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.workflow-validation.v1.schema.json)
 - [Public workflow YAML example](https://github.com/Austin243/ElecTrace/blob/main/examples/electrace.workflow.yaml)
 - [`electrace.benchmark.v0.1` JSON Schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/benchmark-v0.1.schema.json)
 - [Example normalized feature document](examples/electrace.features.v1.example.json)

docs/migration.md

@@ -22,14 +22,23 @@ identifiers.
 | HDF5 schema label | `electrace.analysis` |
 | Default result directory | `electrace-results/` |
 | Default demo directory | `.electrace-demo/` |
-| Version field from `doctor --json` | `electrace_version` |
+| Version field from `doctor --json` | `data.electrace_version` in `electrace.cli.v1` |
 | Built-in demo producer | `electrace-demo` |
 
 Existing TOML table names and previously supported keys are unchanged. New checkouts
 also expose `inputs.descriptor_source` to select local, external, or merged descriptor
 discovery explicitly; newly generated configurations select `auto`. The canonical
 filename, generated defaults, program identifiers, and namespaces changed.
 
+## Machine-readable CLI output in 0.1.0a4
+
+Explicit `--json` output now uses the `electrace.cli.v1` envelope on every operational
+subcommand. Consumers of the earlier pre-release shapes must read the former
+`doctor --json` and `volume --json` payloads below `data`. `plan` and `workflow status`
+retain their original raw JSON when `--json` is omitted; adding the flag requests the
+new envelope. Help and version output remain human-readable and should be requested
+without `--json`.
+
 ## Migrate a development checkout
 
 Use a fresh virtual environment so an older editable installation cannot shadow the

docs/quickstart.md

@@ -38,10 +38,10 @@ records. Without a configuration it checks the runtime and adapter executables;
 initialization, `electrace doctor --config electrace.toml` deterministically checks
 every discovered frame and its required plugin inputs.
 
-With `--json`, unconfigured executable checks appear in the top-level `plugins` array.
-A configured path check uses the top-level `frames` array, whose entries identify each
-frame and contain that frame's plugin reports; consumers should not mistake an empty
-top-level `plugins` array for a skipped configured-path check.
+With `--json`, unconfigured executable checks appear in the `data.plugins` array. A
+configured path check uses `data.frames`, whose entries identify each frame and contain
+that frame's plugin reports; consumers should not mistake an empty `data.plugins` array
+for a skipped configured-path check.
 
 ## 3. Run the deterministic demo
 
@@ -149,20 +149,20 @@ shell-free plan for one plugin, frame, and capability:
 
 ```bash
 electrace plan critic2 /absolute/path/to/neb-images/03 \
-  --capability qtaim_critical_points --config electrace.toml
+  --capability qtaim_critical_points --config electrace.toml --json
 ```
 
 Generate a deterministic plan for every discovered frame by passing the path root:
 
 ```bash
 electrace plan critic2 /absolute/path/to/neb-images --all-frames \
-  --capability qtaim_critical_points --config electrace.toml
+  --capability qtaim_critical_points --config electrace.toml --json
 ```
 
-The one-frame form emits a command-plan object directly. The batch form emits
-`{"plugin": ..., "path": ..., "plans": [...]}`, with `plans` in deterministic frame
-order. Each element contains a canonical `frame` record and a `command` that follows
-the same command-plan contract as the one-frame form.
+With `--json`, the one-frame or batch plan is returned under `data` in an
+`electrace.cli.v1` envelope. Batch `data.plans` remains in deterministic frame order.
+Each element contains a canonical `frame` record and a `command` that follows the same
+command-plan contract as the one-frame form.
 
 The command prints JSON containing the argument vector, working directory, standard
 input, required inputs, and expected outputs. Review it before an authorized workflow
@@ -182,10 +182,14 @@ manifest:
 electrace workflow init electrace-workflow.yaml \
   --images /absolute/path/to/neb-images
 # Edit and review the YAML, executable paths, templates, frames, and scheduler.
+electrace workflow validate electrace-workflow.yaml --json
 electrace workflow stage electrace-workflow.yaml
-electrace workflow status electrace-workflow.yaml
+electrace workflow status electrace-workflow.yaml --json
 ```
 
+`workflow validate` resolves the complete selected job graph without creating the
+workspace or writing any file.
+
 For `scheduler.kind: local`, execution requires an explicit gate:
 
 ```bash

docs/workflows.md

@@ -195,6 +195,23 @@ Comma-separated items are evaluated left to right. An out-of-range explicit inde
 an empty result, a zero slice step, or selecting one frame twice is an error. Quote
 selectors containing `:` so YAML cannot reinterpret them.
 
+## Validate without writing
+
+Resolve the manifest, frame selector, templates, executable vectors, scheduler,
+dependencies, required inputs, and expected outputs before creating a workspace:
+
+```bash
+electrace workflow validate electrace-workflow.yaml --json
+```
+
+Validation is strictly read-only. It does not create the configured workspace, copy a
+template, render a Slurm script, or launch a command. Missing executables are reported
+as warnings because they may be supplied later by a compute-node module environment;
+invalid templates, unresolved inputs, unsafe paths, and invalid job graphs are errors.
+The resolved plan is returned inside an `electrace.cli.v1` response envelope and
+follows the public
+[`electrace.workflow-validation.v1` schema](https://github.com/Austin243/ElecTrace/blob/main/schemas/electrace.workflow-validation.v1.schema.json).
+
 ## Stage and inspect without executing
 
 Staging discovers the selected frames, copies templates and structures, applies
@@ -203,7 +220,7 @@ It does not launch a program:
 
 ```bash
 electrace workflow stage electrace-workflow.yaml
-electrace workflow status electrace-workflow.yaml
+electrace workflow status electrace-workflow.yaml --json
 ```
 
 Use `workflow status` as a filesystem snapshot only. It reports required inputs and
@@ -285,6 +302,12 @@ confirmation. `--yes` invokes `sbatch` (or the executable supplied with
 calculation. Use your site's scheduler tools and then `workflow status` to review the
 jobs and files.
 
+ElecTrace journals every accepted ID in `slurm/submissions.json`. If an authorized
+submission exits `1`, inspect `error.details.partial_submissions`, `record_path`, and
+that journal before retrying. A prior journal blocks another submission even with
+`--force`; archive or remove it only after reconciling every accepted ID. Never
+resubmit an already accepted script blindly.
+
 ## Collect, analyze, and report
 
 After every selected descriptor job has produced its declared output, collection

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "electrace"
-version = "0.1.0a3"
+version = "0.1.0a4"
 description = "Persistent electronic-topology tracking across periodic reaction paths and structure series"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"
@@ -37,7 +37,7 @@ dependencies = [
   "numpy>=1.26",
   "PyYAML>=6.0",
   "rich>=13.7",
-  "typer>=0.12",
+  "typer>=0.20",
 ]
 
 [project.optional-dependencies]