open-local-audit 0.66.0 → 0.67.0

package/docs/architecture/workflow-status.md

@@ -0,0 +1,137 @@
+# Workflow Status
+
+## Purpose
+
+`workflow --status` reports the latest persisted state of one configured
+workflow without running a stage or changing local state.
+
+```bash
+open-local-audit workflow --config workflow.json --status
+open-local-audit workflow --config workflow.json --status --format json
+```
+
+Status is read-only. It makes no network calls, resolves no API keys, creates
+no directories, and writes no files. It reports persisted state; it does not
+claim that a process recorded as running is still alive.
+
+## Current-state manifest
+
+A normal workflow run writes `workflow-state.json` below the configured
+`outDir`. The versioned manifest contains:
+
+- a fingerprint of the validated effective workflow configuration;
+- the persisted lifecycle phase and current stage;
+- the existing workflow stage summary;
+- start and last-update timestamps;
+- a sanitized failure description when execution fails.
+
+The manifest does not contain environment variables, API keys, Google Places
+queries, raw provider responses, or website response bodies. It is replaced
+atomically through the existing guarded workflow output writer.
+
+The initial manifest is persisted before the first workflow stage or network
+call. Each stage start updates the current stage. After a stage succeeds, its
+checkpoint is persisted before the manifest records the successful transition.
+A controlled failure records `failed` only when its failure transition is
+persisted; successful completion records `completed`. If persistence of the
+failure transition fails, the last durable state remains authoritative and can
+report as `running-or-interrupted`, while the workflow command still exits with
+the underlying failure. An abrupt process exit also leaves the last persisted
+running state.
+
+## Checkpoint correlation
+
+The manifest `checkpointHash` is `null` until the first successful checkpoint
+write of the current run. After each successful stage checkpoint write, the
+workflow stores the SHA-256 hash of the exact checkpoint bytes in the manifest.
+`checkpointHash` gates only status `resumeAvailable` and status-generated resume
+recommendations: status accepts correlation only when the manifest hash equals
+the hash of a validated checkpoint. This prevents an older checkpoint for the
+same configuration from enabling status resume advice when a newer run is
+interrupted before writing its first checkpoint. Direct `workflow --resume`
+validates and uses the v1 checkpoint independently; it does not read the state
+manifest and is not gated by this correlation.
+
+Failure to persist the initial manifest prevents stage execution. Failure to
+persist a later transition stops the workflow before another stage begins and
+does not discard the last verified checkpoint. The workflow must never report
+completion when the completed state could not be persisted.
+
+## Status report
+
+Terminal and JSON output are rendered from the same versioned
+`WorkflowStatusReport`. The report status is one of:
+
+- `not-started`: no state or checkpoint exists for the configuration;
+- `running-or-interrupted`: execution last persisted a running state, but
+  process liveness is unknown;
+- `failed`: execution persisted a controlled failure;
+- `completed`: every enabled stage completed successfully;
+- `invalid`: state, configuration identity, checkpoint, or required managed
+  artifacts cannot be trusted.
+
+The report includes the current stage, last successful stage, stage summaries,
+last update time, artifact validation result, resume availability, and a
+structured next action. JSON commands use an argument array instead of a shell
+string so callers do not need to parse quoting.
+
+`resumeAvailable` is true only when the report is not completed and the current
+configuration has a valid checkpoint with the managed artifacts required by
+resume. A `running-or-interrupted` report warns the operator to confirm that no
+workflow process is still active before using `--resume`. An `invalid` report
+never recommends automatic resume.
+
+## Validation and compatibility
+
+Status validates:
+
+- the state structure and version;
+- the effective configuration fingerprint;
+- the existing checkpoint structure and version when resume state is present;
+- the expected managed paths and required artifact integrity.
+
+`workflow-state.json` is not added to `WorkflowManagedPaths` or the existing
+checkpoint output map. The v1 checkpoint and `workflow-summary.json` contracts
+remain unchanged, so checkpoints written by v0.65 and v0.66 remain valid for
+`--resume`.
+
+When no state manifest exists but a valid legacy checkpoint does, status derives
+a conservative report from the checkpoint. A fully completed checkpoint reports
+`completed`; any incomplete checkpoint reports `running-or-interrupted` and may
+offer resume after normal checkpoint validation. A malformed or mismatched
+legacy checkpoint reports `invalid`. This fallback does not rewrite or migrate
+the old files.
+
+## CLI and exit behavior
+
+`--status`, `--check`, `--plan`, and `--resume` are mutually exclusive.
+`--format terminal|json` is accepted with `--status`, `--check`, or `--plan`.
+Supplying `--format` for normal execution or resume remains invalid.
+
+`completed`, `not-started`, and `running-or-interrupted` return exit code `0`.
+`failed`, `invalid`, invalid configuration, and invalid CLI usage return exit
+code `1`. JSON mode writes exactly one report object to standard output; usage
+and configuration errors retain the existing standard-error behavior.
+
+Recommended next actions are:
+
+1. `not-started`: run the workflow normally.
+2. `failed` with a valid checkpoint: run with `--resume`.
+3. `failed` without a checkpoint: run the workflow normally.
+4. `running-or-interrupted`: first confirm that no workflow process is active,
+   then use `--resume` only when the report marks it available.
+5. `completed`: no action.
+6. `invalid`: inspect or replace the untrusted local state; do not resume it.
+
+## Verification contract
+
+Automated coverage must prove:
+
+- every manifest lifecycle transition and atomic replacement behavior;
+- not-started, completed, controlled-failure, and interrupted status reports;
+- configuration fingerprint mismatch and managed-artifact modification;
+- resume availability with valid, missing, and invalid checkpoints;
+- v0.65 and v0.66 checkpoint compatibility;
+- CLI option conflicts, terminal and JSON rendering, and exit codes;
+- no writes, directory creation, network calls, or secret resolution during
+  status inspection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-local-audit",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "Open-source website and local presence auditor for small businesses.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "docs/architecture/workflow-command.md",
     "docs/architecture/workflow-preflight.md",
     "docs/architecture/workflow-plan.md",
-    "docs/architecture/workflow-resume.md"
+    "docs/architecture/workflow-resume.md",
+    "docs/architecture/workflow-status.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",