loki-mode 9.22.8 → 9.22.10

package/README.md

@@ -101,12 +101,17 @@ object instead of terminal text:
 
 ```bash
 loki quickstart "a todo app with user accounts" --dry-run --json > preview.json
+loki quickstart --verify-preview preview.json --json
 loki quickstart --from-preview preview.json --yes
 ```
 
 The object contains the input kind, deterministic selected template (or `null`
 for an existing PRD), the exact estimator response under `plan`, and a bounded
 continuation containing the exact idea/template or the PRD path and SHA-256.
+`--verify-preview` validates the same bounded duplicate-key-rejecting schema and
+requires either a currently shipped idea template or the unchanged digest-bound
+PRD, while emitting no idea or PRD path. It accepts a file or piped stdin and
+returns before provider discovery, estimation, writes, or build execution.
 `--from-preview` requires explicit argv `--yes`, rejects malformed, conflicting,
 symlinked, or changed inputs before provider and build boundaries, then uses the
 existing no-clobber quickstart path. The saved plan is evidence rather than
@@ -394,6 +399,19 @@ honest verdict (VERIFIED / VERIFIED WITH GAPS / NOT VERIFIED), the key facts
 only when the receipt's own headline is VERIFIED. This is on by default whenever
 Loki opens or advises a PR; opt out with `LOKI_PROVEN_PR=0`.
 
+For a review-before-publish workflow, preparation and GitHub mutation are two
+explicit steps:
+
+```bash
+loki start owner/repo#42 --prepare-pr  # builds and writes exact title/body locally
+loki ship --publish                    # pushes that issue branch and opens the PR
+```
+
+The second command consumes `.loki/state/pr-title.txt` and
+`.loki/state/pr-body.md` byte-for-byte. Plain `loki ship`, previews, and default
+start paths remain non-publishing. A failed PR creation preserves both files and
+prints the exact remote-branch rollback command.
+
 An optional advisory status check (`loki: verified-completion`) maps the verdict
 to a GitHub check-run. It is opt-in (`LOKI_PROVEN_PR_CHECK=1`) and can never block
 a merge on its own. To make verified-completion blocking, add it as a required

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v9.22.8
+# Loki Mode v9.22.10
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -470,4 +470,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v9.22.8 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.22.10 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-9.22.8
+9.22.10

package/autonomy/issue-parser.sh

@@ -265,7 +265,7 @@ _gp_criteria_lines() {
 }
 
 # write_journey_context <owner> <repo> <number> <title> <url> <acceptance>
-#                       <files> <type> <priority>
+#                       <files> <type> <priority> [journey-start-epoch]
 #
 # Writes .loki/state/issue-context.json (feature 2: the exact acceptance context)
 # and .loki/state/journey-plan.json (feature 3: the early machine-readable
@@ -277,6 +277,7 @@ _gp_criteria_lines() {
 write_journey_context() {
     local owner="$1" repo="$2" number="$3" title="$4" url="$5"
     local acceptance="$6" files="$7" issue_type="$8" priority="$9"
+    local journey_started_epoch="${10:-}"
 
     local state_dir="${LOKI_DIR:-.loki}/state"
     mkdir -p "$state_dir" 2>/dev/null || return 0
@@ -348,6 +349,34 @@ write_journey_context() {
         rm -f "$plan_tmp" 2>/dev/null || true
     fi
 
+    # The parsed, acceptance-bound plan is the first useful result: it tells the
+    # user what Loki understood and what it will attempt before provider latency
+    # begins. Measure it honestly from command entry when the caller supplied a
+    # valid epoch. This is explicitly a proposed plan, never represented as a
+    # verified patch. Later first-artifact evidence supersedes it in receipts.
+    case "$journey_started_epoch" in
+        ''|*[!0-9]*) ;;
+        *)
+            local now_epoch elapsed first_tmp
+            now_epoch="$(date +%s)"
+            elapsed=$((now_epoch >= journey_started_epoch ? now_epoch - journey_started_epoch : 0))
+            first_tmp="$state_dir/.first-useful-result.$$.json"
+            if jq -n --argjson seconds "$elapsed" \
+                --arg generated_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+                '{schema_version:"1.0", kind:"proposed_solution_plan",
+                  seconds_to_first_result:$seconds,
+                  under_60_seconds:($seconds < 60),
+                  verified_patch:false, generated_at:$generated_at,
+                  artifact:".loki/state/journey-plan.json"}' \
+                > "$first_tmp" 2>/dev/null; then
+                mv -f "$first_tmp" "$state_dir/first-useful-result.json" 2>/dev/null \
+                    || rm -f "$first_tmp"
+            else
+                rm -f "$first_tmp" 2>/dev/null || true
+            fi
+            ;;
+    esac
+
     return 0
 }
 

package/autonomy/lib/gate_policy.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Read-only quality-gate policy reporting for CLI and dashboard consumers."""
+
+import json
+import os
+
+SCHEMA_VERSION = 1
+
+PROMOTABLE = {
+    "magic_debate": ("LOKI_GATE_MAGIC_DEBATE_BLOCKING", "true", "spec-vs-implementation debate"),
+    "test_coverage": ("LOKI_COV_ENFORCE", "1", "project test runner pass/fail"),
+    "policy_approval": ("LOKI_POLICY_APPROVAL_ENFORCE", "1", "staged-autonomy approval policy"),
+}
+
+ALWAYS_BLOCKING = {
+    "static_analysis": "static-analysis findings on the diff",
+    "code_review": "blind review Critical/High findings",
+    "mock_integrity": "tautological assertions and excessive mocking",
+    "mutation_integrity": "test-fitting assertion churn",
+}
+
+
+def _counts(loki_dir):
+    path = os.path.join(loki_dir, "quality", "gate-failure-count.json")
+    try:
+        with open(path, encoding="utf-8") as handle:
+            data = json.load(handle)
+        return data if isinstance(data, dict) else None
+    except (OSError, ValueError):
+        return None
+
+
+def assess(loki_dir=".loki", env=None):
+    """Return policy without mutating files or environment.
+
+    `audit_hits` remains null when the ledger is absent or malformed. Reporting
+    zero there would falsely claim the gate ran and never fired.
+    """
+    env = os.environ if env is None else env
+    counts = _counts(loki_dir)
+    gates = []
+    for name, why in sorted(ALWAYS_BLOCKING.items()):
+        gates.append({
+            "gate": name,
+            "mode": "blocking",
+            "promotable": False,
+            "audit_hits": counts.get(name) if counts is not None else None,
+            "why": why,
+            "promote_with": None,
+        })
+    for name, (variable, value, why) in sorted(PROMOTABLE.items()):
+        enabled = str(env.get(variable, "")).strip().lower() in ("1", "true", "yes")
+        gates.append({
+            "gate": name,
+            "mode": "blocking" if enabled else "advisory",
+            "promotable": True,
+            "audit_hits": counts.get(name) if counts is not None else None,
+            "why": why,
+            "promote_with": None if enabled else f"{variable}={value}",
+        })
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "status": "measured",
+        "ledger": "present" if counts is not None else "absent",
+        "gates": gates,
+    }

package/autonomy/lib/proof-generator.py

@@ -1031,13 +1031,24 @@ def _collect_journey(loki_dir):
         },
     }
 
-    # Time to first useful result. Reuses the number run.sh already writes; we
-    # do not add a second writer and we never synthesize the value.
+    # Time to first useful result. Prefer the first verified code artifact when
+    # one exists. Before that, issue mode can truthfully report its acceptance-
+    # bound proposed plan, explicitly labelled as NOT a verified patch.
     fa = _read_json(os.path.join(state, "first-artifact.json"), default=None)
     if isinstance(fa, dict):
         v = fa.get("seconds_to_first_artifact")
         if isinstance(v, (int, float)) and v >= 0:
             out["time_to_first_result_sec"] = int(v)
+            out["first_result_kind"] = "code_change"
+            out["first_result_verified_patch"] = True
+    else:
+        fr = _read_json(os.path.join(state, "first-useful-result.json"), default=None)
+        if isinstance(fr, dict):
+            v = fr.get("seconds_to_first_result")
+            if isinstance(v, (int, float)) and v >= 0:
+                out["time_to_first_result_sec"] = int(v)
+                out["first_result_kind"] = str(fr.get("kind") or "")
+                out["first_result_verified_patch"] = bool(fr.get("verified_patch") is True)
 
     # Human interventions. Fills the socket trust_trajectory.py:145 already
     # reads and documents as "no per-run counter persisted today". Absent file

package/autonomy/lib/proof-pr.sh

@@ -220,7 +220,12 @@ def main():
 
         ttfr = journey.get("time_to_first_result_sec")
         if isinstance(ttfr, int):
-            _line("| Time to first result | " + str(ttfr) + "s |")
+            first_kind = str(journey.get("first_result_kind") or "").strip()
+            if first_kind == "proposed_solution_plan":
+                _line("| First useful result | proposed plan in " + str(ttfr)
+                      + "s (not a verified patch) |")
+            else:
+                _line("| Time to first result | " + str(ttfr) + "s |")
 
         ivs = journey.get("interventions")
         if isinstance(ivs, int):

package/autonomy/loki

@@ -4617,6 +4617,89 @@ cmd_next() {
 }
 
 # loki ship -- the build is done, now get it out (review + PR advice in one flow).
+# Publish an already-prepared PR. This is deliberately a separate, explicit
+# mutation boundary from the default print-only `loki ship` flow. Preparation
+# writes the exact reviewed title/body under .loki/state; publishing consumes
+# those bytes without rebuilding, re-rendering, or inventing evidence.
+publish_prepared_pr() {
+    local state_dir="${LOKI_DIR:-.loki}/state"
+    local title_file="$state_dir/pr-title.txt"
+    local body_file="$state_dir/pr-body.md"
+    local pr_state="$state_dir/pr.json"
+
+    if [ ! -s "$title_file" ] || [ ! -s "$body_file" ]; then
+        echo "Error: no prepared PR found. Run 'loki start <issue> --prepare-pr' first." >&2
+        return 2
+    fi
+    if ! command -v git >/dev/null 2>&1 || ! git rev-parse --git-dir >/dev/null 2>&1; then
+        echo "Error: publishing a prepared PR requires a git repository." >&2
+        return 2
+    fi
+    if ! command -v gh >/dev/null 2>&1; then
+        echo "Error: publishing a prepared PR requires the GitHub CLI (gh)." >&2
+        return 2
+    fi
+
+    local branch base title existing_url pr_url tmp_state
+    branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+    case "$branch" in
+        ""|HEAD|main|master)
+            echo "Error: refusing to publish prepared work from '$branch'; check out its issue branch." >&2
+            return 2 ;;
+    esac
+    if ! git remote get-url origin >/dev/null 2>&1; then
+        echo "Error: publishing a prepared PR requires an 'origin' remote." >&2
+        return 2
+    fi
+    title="$(cat "$title_file")"
+    if [ -z "$title" ]; then
+        echo "Error: prepared PR title must be one non-empty line." >&2
+        return 2
+    fi
+    case "$title" in
+        *$'\n'*)
+            echo "Error: prepared PR title must be one non-empty line." >&2
+            return 2 ;;
+    esac
+
+    # Idempotence: an interrupted/retried publish reuses the open PR and never
+    # creates a duplicate. This read-only query occurs only after --publish.
+    existing_url="$(gh pr list --head "$branch" --state open --json url --jq '.[0].url // empty' 2>/dev/null || true)"
+    if [ -n "$existing_url" ]; then
+        pr_url="$existing_url"
+    else
+        # Do not attempt PR creation after a failed push. The prepared body
+        # remains local and byte-identical, so the operator can fix auth/network
+        # and retry. A successful push followed by create failure is reversible
+        # with the exact command printed below.
+        if ! git push --set-upstream origin "$branch"; then
+            echo "Error: branch push failed; prepared PR files were preserved." >&2
+            return 1
+        fi
+        if ! pr_url="$(gh pr create --head "$branch" --title "$title" --body-file "$body_file")"; then
+            echo "Error: PR creation failed; prepared PR files were preserved." >&2
+            echo "Rollback remote branch: git push origin --delete $branch" >&2
+            return 1
+        fi
+        pr_url="$(printf '%s\n' "$pr_url" | grep -Eo 'https://[^[:space:]]+' | head -1)"
+        if [ -z "$pr_url" ]; then
+            echo "Error: gh reported success without a PR URL; prepared files were preserved." >&2
+            echo "Inspect: gh pr list --head $branch" >&2
+            return 1
+        fi
+    fi
+
+    mkdir -p "$state_dir" || return 1
+    tmp_state="$pr_state.tmp.$$"
+    if command -v jq >/dev/null 2>&1; then
+        jq -n --arg url "$pr_url" --arg branch "$branch" --arg title "$title" \
+            '{state:"created", url:$url, branch:$branch, title:$title,
+              body_path:".loki/state/pr-body.md"}' > "$tmp_state" \
+            && mv "$tmp_state" "$pr_state" || { rm -f "$tmp_state"; return 1; }
+    fi
+    echo "PR ready: $pr_url"
+}
+
 # Composes existing surfaces only: optionally opens the running app (--preview),
 # runs the SAME diff quality gates as cmd_review, and on a clean-enough result
 # prints the exact branch-aware PR command via the shared print_pr_advice (the
@@ -4626,6 +4709,7 @@ cmd_next() {
 # and points at the findings instead of advising a PR.
 cmd_ship() {
     local do_preview=false
+    local publish=false
     local review_args=()
     # Tracks whether the caller passed an explicit scope flag (--staged, --since,
     # ...). Passthrough flags like --yes/--severity do NOT set this, so they do
@@ -4637,6 +4721,7 @@ cmd_ship() {
                 echo -e "${BOLD}Loki Mode -- finish the build: review, then PR advice (print-only)${NC}"
                 echo ""
                 echo "Usage: loki ship [--preview] [--yes] [review options]"
+                echo "       loki ship --publish"
                 echo ""
                 echo "Runs the natural finish line in one command:"
                 echo "  1. (with --preview) opens the app Loki built and started locally"
@@ -4645,13 +4730,15 @@ cmd_ship() {
                 echo "  3. on a clean-enough result, PRINTS the exact branch-aware"
                 echo "     git push + pull-request command for YOU to run"
                 echo ""
-                echo "It is advisory only for shipping: it NEVER runs 'git push', NEVER"
-                echo "creates a PR, and NEVER deploys. You run the printed command."
+                echo "The default flow is advisory only: it NEVER runs 'git push' or"
+                echo "creates a PR. --publish is the explicit mutation boundary: it"
+                echo "publishes the exact title/body previously written by --prepare-pr."
                 echo "If review finds HIGH or CRITICAL findings it stops and points you"
                 echo "at the findings instead of advising a PR (exit code 1)."
                 echo ""
                 echo "Options:"
                 echo "  --preview    Open the running local app first (loki preview)"
+                echo "  --publish    Push the current issue branch and publish its prepared PR"
                 echo "  --yes, -y    Pass through to review (skip its confirmation prompt)"
                 echo "  --help, -h   Show this help and exit"
                 echo ""
@@ -4660,6 +4747,7 @@ cmd_ship() {
                 return 0
                 ;;
             --preview) do_preview=true ;;
+            --publish) publish=true ;;
             # Only a known set of NON-scope passthrough flags are exempt from
             # "explicit scope". Everything else the caller passes -- an explicit
             # scope flag (--staged/--since/...), a positional <file-or-dir>, or any
@@ -4689,6 +4777,15 @@ cmd_ship() {
         shift
     done
 
+    if [ "$publish" = true ]; then
+        if [ "$do_preview" = true ] || [ "${#review_args[@]}" -gt 0 ]; then
+            echo "Error: --publish cannot be combined with preview/review options." >&2
+            return 2
+        fi
+        publish_prepared_pr
+        return $?
+    fi
+
     # 1. Optional preview of the running local app. Only when an app-runner state
     #    file exists, so we never imply an app is running when it is not.
     if [ "$do_preview" = true ]; then
@@ -9694,6 +9791,12 @@ cmd_issue_view() {
 #===============================================================================
 
 cmd_run() {
+    # Wall-clock anchor for the issue journey. Captured before argument parsing,
+    # auth, or issue fetch so the first-result measurement includes the wait the
+    # user actually experiences. Exported only through the explicit writer call
+    # below; it does not alter runner/provider behavior.
+    local _issue_journey_started_epoch
+    _issue_journey_started_epoch="$(date +%s)"
     # v6.84.0: `loki run` is now a deprecated alias for `loki start <issue-ref>`.
     # When invoked directly (not via the unified start dispatcher), emit a
     # deprecation notice and a telemetry event so we can track adoption of the
@@ -10060,7 +10163,8 @@ cmd_run() {
             _gp_acc=$(extract_acceptance_criteria "$_gp_body" 2>/dev/null || true)
         fi
         write_journey_context "$_gp_owner" "$_gp_repo" "${number:-}" "$title" \
-            "$url" "$_gp_acc" "" "${issue_provider:-github}" "" 2>/dev/null || true
+            "$url" "$_gp_acc" "" "${issue_provider:-github}" "" \
+            "$_issue_journey_started_epoch" 2>/dev/null || true
     fi
 
     # Per-session locking (v6.4.0): export session ID so run.sh uses

package/autonomy/quickstart.sh

@@ -623,6 +623,86 @@ PY
     python3 -c "$validator_code" "$preview_path"
 }
 
+# _qs_verify_preview <path> <json>: prove that one bounded schema-v1 preview is
+# still actionable without crossing provider, estimator, PRD-write, or build
+# boundaries. Idea previews must name a currently shipped template. PRD
+# previews must still resolve to the exact readable non-symlink file digest.
+# Output deliberately excludes the idea and PRD path.
+_qs_verify_preview() {
+    local preview_path="$1" json_output="${2:-false}"
+    local fields="" kind="" template="" encoded="" digest="" value=""
+    fields=$(_qs_load_preview "$preview_path") || {
+        printf 'Preview JSON is malformed or incompatible.\n' >&2
+        return 2
+    }
+    IFS='|' read -r kind template encoded digest <<< "$fields"
+    value=$(python3 -c 'import base64,sys; sys.stdout.buffer.write(base64.b64decode(sys.argv[1], validate=True))' "$encoded" 2>/dev/null) || {
+        printf 'Preview JSON continuation is invalid.\n' >&2
+        return 2
+    }
+    [ -n "$value" ] || {
+        printf 'Preview JSON continuation is empty.\n' >&2
+        return 2
+    }
+
+    local verdict=""
+    if [ "$kind" = "idea" ]; then
+        if ! _qs_template_exists "$template"; then
+            printf 'Preview template is not currently shipped: %s\n' "$template" >&2
+            return 2
+        fi
+        verdict="SHIPPED_TEMPLATE_MATCH"
+    elif [ "$kind" = "prd" ]; then
+        if [ ! -f "$value" ] || [ ! -r "$value" ] || [ -L "$value" ]; then
+            printf 'Preview PRD is not a readable regular non-symlink file.\n' >&2
+            return 2
+        fi
+        local current_digest=""
+        current_digest=$(shasum -a 256 "$value" 2>/dev/null | awk '{print $1}') || current_digest=""
+        if [ -z "$current_digest" ] || [ "$current_digest" != "$digest" ]; then
+            printf 'Preview PRD has changed since the saved preview; run --dry-run --json again.\n' >&2
+            return 2
+        fi
+        verdict="EXACT_PRD_MATCH"
+    else
+        printf 'Preview JSON continuation kind is unsupported.\n' >&2
+        return 2
+    fi
+
+    if [ "$json_output" = true ]; then
+        python3 - "$kind" "$template" "$digest" "$verdict" <<'PY'
+import json
+import sys
+
+kind, template, digest, verdict = sys.argv[1:5]
+json.dump(
+    {
+        "command": "loki quickstart",
+        "input_kind": kind,
+        "mode": "verify-preview",
+        "prd_sha256": digest if kind == "prd" else None,
+        "schema_version": 1,
+        "selected_template": template if kind == "idea" else None,
+        "valid": True,
+        "verdict": verdict,
+    },
+    sys.stdout,
+    separators=(",", ":"),
+    sort_keys=True,
+)
+sys.stdout.write("\n")
+PY
+        return $?
+    fi
+
+    if [ "$kind" = "idea" ]; then
+        printf 'VERIFIED / %s / template=%s\n' "$verdict" "$template"
+    else
+        printf 'VERIFIED / %s / sha256=%s\n' "$verdict" "$digest"
+    fi
+    return 0
+}
+
 # _qs_help: concise usage for `loki quickstart --help`.
 _qs_help() {
     printf '%sloki quickstart%s - guided first build (setup, idea, template, plan, go)\n' "$_QS_BOLD" "$_QS_NC"
@@ -639,8 +719,9 @@ _qs_help() {
     printf 'Options:\n'
     printf '  --yes, -y     Auto-confirm the final build prompt (still shows the plan)\n'
     printf '  --dry-run     Preview the selected template and plan; write/start nothing\n'
-    printf '  --json        With --dry-run, emit one machine-readable JSON object\n'
+    printf '  --json        Emit machine-readable output for a read-only command\n'
     printf '  --from-preview F  Continue saved JSON from file F (or - for piped stdin); requires --yes\n'
+    printf '  --verify-preview F  Verify saved JSON from file F (or - for piped stdin); executes nothing\n'
     printf '  --template N  Use the exact shipped template N for an IDEA\n'
     printf '  --list-templates  List every shipped template and its purpose\n'
     printf '  --help, -h    Show this help and exit\n'
@@ -660,6 +741,7 @@ _qs_help() {
     printf '  Add --json for versioned JSON only; --json requires --dry-run.\n'
     printf '  Save that JSON, then continue it with --from-preview FILE --yes.\n'
     printf '  Or pipe it with --from-preview - --yes; terminal stdin is refused.\n'
+    printf '  Verify it without execution using --verify-preview FILE (and optional --json).\n'
     printf '\n'
     printf 'Steps:\n'
     printf '  1. Setup      Check for an AI provider for execution (skipped in preview)\n'
@@ -697,6 +779,8 @@ cmd_quickstart() {
     local list_templates_flag_seen=false
     local from_preview=""
     local from_preview_flag_seen=false
+    local verify_preview=""
+    local verify_preview_flag_seen=false
     local preview_prd_digest=""
     if _qs_assume_yes; then assume_yes=true; fi
 
@@ -765,6 +849,19 @@ cmd_quickstart() {
                 from_preview="$2"
                 shift 2
                 ;;
+            --verify-preview)
+                if [ "$verify_preview_flag_seen" = true ]; then
+                    printf '%s--verify-preview may be specified only once.%s\n' "$_QS_RED" "$_QS_NC" >&2
+                    exit 2
+                fi
+                verify_preview_flag_seen=true
+                if [ $# -lt 2 ] || [ -z "${2:-}" ] || [[ "${2:-}" == --* ]]; then
+                    printf '%s--verify-preview requires a preview JSON path.%s\n' "$_QS_RED" "$_QS_NC" >&2
+                    exit 2
+                fi
+                verify_preview="$2"
+                shift 2
+                ;;
             --*)
                 printf '%sUnknown option: %s%s\n' "$_QS_RED" "$1" "$_QS_NC" >&2
                 printf "Run 'loki quickstart --help' for usage.\n" >&2
@@ -783,6 +880,18 @@ cmd_quickstart() {
         esac
     done
 
+    # Verification is a standalone read-only shape. It accepts only optional
+    # JSON formatting, validates the full current continuation boundary, and
+    # returns before terminal, provider, estimator, PRD-write, and build seams.
+    if [ "$verify_preview_flag_seen" = true ]; then
+        if [ -n "$positional" ] || [ "$yes_flag" = true ] || [ "$dry_run" = true ] || [ "$template_flag_seen" = true ] || [ "$list_templates" = true ] || [ "$from_preview_flag_seen" = true ]; then
+            printf '%s--verify-preview accepts only a preview JSON path and optional --json.%s\n' "$_QS_RED" "$_QS_NC" >&2
+            exit 2
+        fi
+        _qs_verify_preview "$verify_preview" "$json_output"
+        return $?
+    fi
+
     # Continuation is a standalone execution shape. Explicit argv consent is
     # mandatory, and no caller-supplied input or selector may compete with the
     # reviewed preview. Validation happens before every provider, estimator,