loki-mode 9.19.1 → 9.21.0

package/autonomy/loki

@@ -750,7 +750,11 @@ loki_remote_fetch_receipt() {
     printf '%s' "$resp" > "$tmp" && mv "$tmp" "$dir/proof.json"
     echo "  Evidence Receipt: $dir/proof.json"
 
-    loki_remote_verify_receipt "$dir/proof.json"
+    # The URL is passed so the receipt's attestation can be checked against that
+    # server's published JWKS. Without it the attestation is simply not checked
+    # and the verdict falls back to the gpg path, which is the pre-existing
+    # behaviour rather than a downgrade.
+    loki_remote_verify_receipt "$dir/proof.json" "$url"
 }
 
 # Verify a fetched receipt locally and print exactly what was and was not
@@ -801,6 +805,121 @@ PY
     esac
 }
 
+# Check a receipt's JWKS attestation against the server's PUBLISHED key set.
+#
+# This is the half gpg cannot do over a network. gpg proves provenance only if
+# you already hold the publisher's key, which a submitter who ran
+# `loki start --remote` never does -- so the honest gpg outcome there is
+# NOT CHECKED, and it stays that way until someone performs an out-of-band key
+# import. Fetching /.well-known/jwks.json over the same TLS the API already
+# uses removes that step.
+#
+# Prints "ok", "bad", or "" (could not check). Fails toward "" so an
+# unreachable JWKS never manufactures a verdict in either direction -- an
+# absent measurement is not evidence, and inventing a PASS here would be worse
+# than inventing a FAIL.
+loki_remote_attestation_status() {
+    local pj="$1" url="$2"
+    [ -n "$url" ] || { printf ''; return 0; }
+    command -v python3 >/dev/null 2>&1 || { printf ''; return 0; }
+    local tok
+    tok="$(jq -r '.verification.attestation // empty' "$pj" 2>/dev/null)"
+    [ -n "$tok" ] || { printf ''; return 0; }
+    python3 - "$pj" "$url" "${_LOKI_SCRIPT_DIR}" <<'PY' 2>/dev/null || printf ''
+import json, sys, hashlib, urllib.request
+sys.path.insert(0, sys.argv[3])
+try:
+    from receipt_jwt import verify_attestation
+except ImportError:
+    sys.exit(1)          # -> "" : cannot check, never a verdict
+proof = json.load(open(sys.argv[1]))
+tok = (proof.get("verification") or {}).get("attestation") or ""
+if not tok:
+    sys.exit(1)
+try:
+    with urllib.request.urlopen(
+            sys.argv[2].rstrip("/") + "/.well-known/jwks.json", timeout=10) as r:
+        jwks = json.loads(r.read())
+except Exception:
+    sys.exit(1)          # unreachable JWKS is UNCHECKED, not a failure
+ok, claims = verify_attestation(tok, jwks)
+if not ok:
+    print("bad"); sys.exit(0)
+# The signature verifying is not enough on its own: it must attest to THIS
+# receipt. Recompute the digest the same way the receipt records it (with
+# `verification` stripped) and require the signed claim to match, or a valid
+# token lifted from a different run would vouch for these bytes.
+proof.pop("verification", None)
+canon = json.dumps(proof, sort_keys=True, separators=(",", ":")).encode()
+print("ok" if claims.get("receipt_sha256") == hashlib.sha256(canon).hexdigest()
+      else "bad")
+PY
+}
+
+# Check a receipt's attestation against a key set given as a URL OR a file.
+#
+# The file form is what makes this usable by a third party with no network and
+# no Loki install: hand them proof.json and jwks.json and they can check both
+# integrity and provenance themselves. That is the whole claim -- "a receipt you
+# can check yourself" is false if checking requires our infrastructure.
+#
+# Prints "ok", "bad", "none" (no attestation present), or "" (could not check).
+# "none" and "" are deliberately distinct: one is a fact about the receipt, the
+# other is an absent measurement, and collapsing them would report an unchecked
+# receipt as an unattested one.
+# NOTE: this shares its verification logic with loki_remote_attestation_status
+# above. The two differ only in their key-set source (that one is URL-only, from
+# a live fetch during a --remote run; this one also accepts a FILE for the
+# offline third-party case). If you change the digest-recompute rule, CHANGE
+# BOTH -- they are covered by different tests
+# (test-remote-attestation-verdict.sh and test-proof-verify-jwks.sh), so a
+# one-sided edit passes one suite and silently weakens the other. Mutation
+# testing found exactly this: a mutation applied to the first copy left every
+# assertion of the second suite green.
+loki_proof_attestation_check() {
+    local pj="$1" src="$2"
+    [ -n "$src" ] || { printf ''; return 0; }
+    command -v python3 >/dev/null 2>&1 || { printf ''; return 0; }
+    python3 - "$pj" "$src" "${_LOKI_SCRIPT_DIR}" <<'PY' 2>/dev/null || printf ''
+import json, sys, os, hashlib, urllib.request
+sys.path.insert(0, sys.argv[3])
+try:
+    from receipt_jwt import verify_attestation
+except ImportError:
+    sys.exit(1)                      # "" : cannot check
+try:
+    proof = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(1)
+tok = (proof.get("verification") or {}).get("attestation") or ""
+if not tok:
+    print("none"); sys.exit(0)       # a FACT about the receipt, not an error
+src = sys.argv[2]
+try:
+    if os.path.isfile(src):
+        jwks = json.load(open(src))
+    else:
+        if not src.startswith(("http://", "https://")):
+            sys.exit(1)
+        url = src if src.rstrip("/").endswith("jwks.json") else \
+            src.rstrip("/") + "/.well-known/jwks.json"
+        with urllib.request.urlopen(url, timeout=10) as r:
+            jwks = json.loads(r.read())
+except Exception:
+    sys.exit(1)                      # "" : unreachable/unreadable, no verdict
+ok, claims = verify_attestation(tok, jwks)
+if not ok:
+    print("bad"); sys.exit(0)
+# A verifying signature is not enough: it must attest to THESE bytes. Recompute
+# the digest the way the receipt records it, so a token lifted from another run
+# cannot vouch for this one.
+proof.pop("verification", None)
+canon = json.dumps(proof, sort_keys=True, separators=(",", ":")).encode()
+print("ok" if claims.get("receipt_sha256") == hashlib.sha256(canon).hexdigest()
+      else "bad")
+PY
+}
+
 loki_remote_verify_receipt() {
     local pj="$1"
     local verifier="${_LOKI_SCRIPT_DIR}/lib/proof-verify.py"
@@ -828,6 +947,10 @@ loki_remote_verify_receipt() {
     # a gate that cries wolf every time trains users to ignore the verdict.
     # Only hash_ok and gpg_ok are load-bearing here; drift is not our verdict.
     local out hash_ok gpg_ok
+    # Second argument is the remote URL when this receipt came from a cluster;
+    # empty for a local receipt, which simply means no attestation is checked.
+    local _attest_url="${2:-}" _attest=""
+    _attest="$(loki_remote_attestation_status "$pj" "$_attest_url")"
     out="$(python3 "$verifier" "$pj" "${TARGET_DIR:-.}" 2>/dev/null)"
     hash_ok="$(printf '%s' "$out" | jq -r '.hash_ok // false' 2>/dev/null)"
     gpg_ok="$(printf '%s' "$out" | jq -r '.gpg_ok | tostring' 2>/dev/null)"
@@ -849,6 +972,18 @@ loki_remote_verify_receipt() {
         echo "    the build ran elsewhere. Not tampering, and not part of the verdict."
     fi
 
+    # An attestation that does not verify is an ACCUSATION, and it is checked
+    # before the gpg branches because it is the stronger statement: the server's
+    # own published key says this token does not cover these bytes. Either the
+    # receipt was altered after the server signed it, or the token was lifted
+    # from a different run. Both mean: do not trust this build.
+    if [ "$_attest" = "bad" ]; then
+        echo -e "  ${RED}TAMPERED: the receipt's attestation does not verify against the server's published keys.${NC}" >&2
+        echo "    Either these bytes were altered after signing, or the attestation" >&2
+        echo "    belongs to a different run. Do not trust this build." >&2
+        return 1
+    fi
+
     # gpg_ok=false covers TWO facts that must never be conflated: the signature
     # is cryptographically bad over this content (the receipt was ALTERED), and
     # gpg could not evaluate it at all (we do not hold the public key). Only the
@@ -866,6 +1001,17 @@ loki_remote_verify_receipt() {
             _why="$(loki_remote_gpg_status "$pj")"
         fi
         if [ "$_why" = "nopubkey" ]; then
+            # JWKS exists precisely for this case: the gpg key is absent, but a
+            # remote-issued receipt can still prove provenance against the
+            # server's published key set, with no out-of-band import.
+            if [ "$_attest" = "ok" ]; then
+                echo -e "  ${GREEN}VERIFIED${NC}: integrity hash matches and the receipt's attestation is valid."
+                echo "    Proven: these bytes are unaltered, and the build server signed them"
+                echo "    with a key published at ${_attest_url}/.well-known/jwks.json."
+                echo "    The gpg key is not in your keyring; the attestation covers provenance."
+                echo "    NOT proven: that the code is correct. A receipt records which checks ran."
+                return 0
+            fi
             echo -e "  ${YELLOW}NOT CHECKED${NC}: the receipt is signed, but the signing key is not in your keyring." >&2
             echo "    Nothing is wrong with the contents: the integrity hash matches. The" >&2
             echo "    signature could not be evaluated, so PROVENANCE is unproven here." >&2
@@ -897,6 +1043,20 @@ loki_remote_verify_receipt() {
         return 0
     fi
 
+    # No gpg signature, but a verified attestation. This is the normal shape for
+    # a cluster build: the receiver signs, the build never holds a gpg key, and
+    # provenance is still proven -- so calling it UNSIGNED would understate what
+    # was actually checked, the mirror of the error we refuse in the other
+    # direction.
+    if [ "$_attest" = "ok" ]; then
+        echo -e "  ${GREEN}VERIFIED${NC}: integrity hash matches and the receipt's attestation is valid."
+        echo "    Proven: these bytes are unaltered, and they were signed by the build"
+        echo "    server whose key is published at ${_attest_url}/.well-known/jwks.json."
+        echo "    Verify that server is one you trust."
+        echo "    NOT proven: that the code is correct. A receipt records which checks ran."
+        return 0
+    fi
+
     echo -e "  ${YELLOW}UNSIGNED${NC}: integrity hash matches. This is NOT proof of provenance."
     echo "    Proven: the receipt is internally consistent with its own hash."
     echo "    NOT proven: who produced it. An unsigned receipt is forgeable -- whoever"
@@ -1501,7 +1661,7 @@ show_landing() {
 }
 
 # Detect argument type for unified `loki start` (v6.84.0)
-# Returns one of: prd | issue | empty | unknown
+# Returns one of: prd | issue | repo | empty | unknown
 # Logic:
 #   - empty arg -> "empty"
 #   - file path ending in .md/.json/.txt AND exists on disk -> "prd"
@@ -1565,7 +1725,10 @@ detect_arg_type() {
     # BUT only if a file with that literal name does NOT exist on disk
     # (ambiguity resolution: files-on-disk win over issue-number heuristic).
     if [[ "$arg" =~ ^#?[0-9]+$ ]]; then
-        if [ -e "$arg" ]; then
+        if [ -d "$arg" ]; then
+            # Directory on disk wins -- same rule as the -d branch below.
+            echo "repo"
+        elif [ -e "$arg" ]; then
             # File on disk wins -- treat as PRD
             echo "prd"
         else
@@ -1574,6 +1737,20 @@ detect_arg_type() {
         return 0
     fi
 
+    # An existing DIRECTORY is a repo to improve, not a spec to build from.
+    # Before this, a directory fell into the "prd" branch below and was handed
+    # to run.sh as a PRD path; it has no .md-family extension, so the
+    # not-found guard skipped it and the run silently proceeded as if no spec
+    # had been given. `loki start <dir>` now means "work on that repo".
+    # ponytail: a directory named `spec.md` still returns "prd" -- the
+    # extension branch at the top of this function wins. Deliberate: an
+    # explicit spec extension is the stronger signal. Move this block above
+    # that branch if directories-with-spec-names ever matter.
+    if [ -d "$arg" ]; then
+        echo "repo"
+        return 0
+    fi
+
     # An existing file on disk is unambiguously a PRD, even if its name has
     # spaces -- a real path the user pointed at wins over the brief heuristic.
     if [ -e "$arg" ]; then
@@ -1844,6 +2021,8 @@ cmd_start() {
     local mirofish_bg=false
     local mirofish_disabled=false
     local no_plan=false  # v6.81.1: --no-plan opts out of auto-plan display
+    local repo_depth="full"          # repository targets default to full verification
+    local repo_depth_explicit=""     # "" | "fast" | "full" -- what the operator asked for
     local remote_url="${LOKI_REMOTE_URL:-}"   # --remote: submit to a deployed cluster
 
     # v6.84.0: unified entry point -- explicit mode overrides + issue-mode args
@@ -1862,9 +2041,10 @@ cmd_start() {
             --help|-h)
                 echo -e "${BOLD}loki start${NC} - Unified entry point for Loki Mode (v6.84.0)"
                 echo ""
-                echo "Usage: loki start [PRD|ISSUE-REF] [options]"
+                echo "Usage: loki start [REPO|PRD|ISSUE-REF] [options]"
                 echo ""
                 echo "Modes (auto-detected from input):"
+                echo "  REPO mode   - existing directory -> one bounded verified improvement"
                 echo "  PRD mode    - path ending in .md/.json/.txt/.yaml -> build from PRD"
                 echo "  ISSUE mode  - GitHub/GitLab/Jira/Azure DevOps URL, owner/repo#N,"
                 echo "                PROJ-123, #123, or bare number -> generate PRD from issue"
@@ -1873,6 +2053,7 @@ cmd_start() {
                 echo "  no input    - analyze current directory, auto-generate PRD"
                 echo ""
                 echo "Arguments:"
+                echo "  REPO                  Existing project directory"
                 echo "  PRD                   Path to PRD file (.md/.json/.txt/.yaml)"
                 echo "  ISSUE-REF             Issue URL, number, or tracker key (see above)"
                 echo ""
@@ -1913,6 +2094,10 @@ cmd_start() {
                 echo "  --mirofish-bg         Run MiroFish pipeline in background"
                 echo "  --no-mirofish         Disable MiroFish even if env var is set"
                 echo "  --no-plan             Skip auto-shown PRD analysis at startup"
+                echo "  --fast                REPO mode: capped lightweight pass, gates reduced"
+                echo "                        (no council verdict; alias --repo-fast)"
+                echo "  --full                REPO mode: explicit full verification, the default"
+                echo "                        (wins over --fast; alias --repo-full)"
                 echo "  --brief \"TEXT\"        Zero-config fast first run from a one-line brief"
                 echo "  --yes, -y             Skip confirmation prompts (auto-confirm)"
                 echo "  --quiet               Suppress [INFO]/[STEP]; warnings and errors still print"
@@ -1947,6 +2132,7 @@ cmd_start() {
                 echo ""
                 echo "Examples:"
                 echo "  loki start                              # Interactive, analyze current dir"
+                echo "  loki start ./my-project                 # Improve an existing project"
                 echo "  loki start \"build a todo app\"           # BRIEF mode (zero-config fast run)"
                 echo "  loki start --brief \"snake\"              # BRIEF mode (single-word escape hatch)"
                 echo "  loki start ./prd.md                     # PRD mode"
@@ -2265,6 +2451,22 @@ cmd_start() {
                 no_plan=true
                 shift
                 ;;
+            --fast|--repo-fast)
+                # Fail closed on a conflict, same doctrine as --isolation below:
+                # never silently downgrade to weaker verification than asked for.
+                # --full wins regardless of order, so `--fast --full` and
+                # `--full --fast` both keep the gates ON.
+                if [ "$repo_depth_explicit" != "full" ]; then
+                    repo_depth="fast"
+                    repo_depth_explicit="fast"
+                fi
+                shift
+                ;;
+            --full|--repo-full)
+                repo_depth="full"
+                repo_depth_explicit="full"
+                shift
+                ;;
             --brief)
                 # R7: explicit one-line brief (escape hatch for single-word
                 # briefs that detect_arg_type would otherwise treat as a PRD
@@ -2557,6 +2759,22 @@ cmd_start() {
         detected_type="empty"
     fi
 
+    # Resolve the directory while the positional path is still relative to the
+    # caller, then enter it before creating any .loki state. Quoted `cd --`
+    # keeps spaces and shell metacharacters inert.
+    if [ "$detected_type" = "repo" ]; then
+        local repo_target
+        repo_target=$(cd -- "$positional_arg" 2>/dev/null && pwd -P) || {
+            echo -e "${RED}Error: cannot enter repository directory: $positional_arg${NC}" >&2
+            return 1
+        }
+        cd -- "$repo_target" || return 1
+        if [ "$LOKI_DIR" = ".loki" ]; then
+            LOKI_DIR="$repo_target/.loki"
+        fi
+        export LOKI_REPO_TARGET="$repo_target"
+    fi
+
     # ISSUE mode: delegate to cmd_run's code path. To avoid duplicating ~450
     # lines of issue-fetching + PR-creation logic, we re-dispatch through
     # cmd_run with reconstructed args. cmd_run then calls cmd_start again
@@ -2638,12 +2856,66 @@ cmd_start() {
         echo ""
     fi
 
+    # REPO mode: `loki start <directory>`. We already cd'd into the target
+    # above, so this is the no-arg codebase path with one difference -- a
+    # synthesized brief that bounds the work to ONE high-value improvement
+    # instead of "build out the whole project".
+    #
+    # The DEFAULT and `--full` deliberately do NOT call
+    # set_ttfv_lightweight_profile: that helper turns the council and the
+    # code-review phase OFF, and the whole point of this entry point is to hand
+    # back VERIFIED evidence. Scope is bounded by the brief text, not by
+    # disabling the gates that check the work. Those runs keep full depth and
+    # report LOKI_TTFV=repo -- the same honest full-depth signal the no-arg path
+    # uses.
+    #
+    # `--fast` is the opt-in exception: it applies the SAME lightweight profile
+    # the brief path uses (capped iterations, council off, simple tier, heavy
+    # phases off) and reports LOKI_TTFV=repo-fast, a distinct signal so the
+    # end-of-run wording in run.sh cannot claim council verdicts that never ran.
+    if [ "$detected_type" = "repo" ]; then
+        local version
+        version=$(get_version)
+        # Same cap the brief sub-path reads, so "fast" means one thing.
+        local _repo_max_iter="${LOKI_MAX_ITERATIONS:-3}"
+        mkdir -p "$LOKI_DIR" 2>/dev/null || true
+        find "$LOKI_DIR" -maxdepth 1 -name 'repo-prd-*.md' -mtime +1 -delete 2>/dev/null || true
+        local repo_prd="$LOKI_DIR/repo-prd-$$.md"
+        synthesize_repo_prd "$repo_prd" "$repo_depth"
+        prd_file="$repo_prd"
+
+        if [ "$repo_depth" = "fast" ]; then
+            set_ttfv_lightweight_profile "$_repo_max_iter"
+            export LOKI_TTFV=repo-fast
+            no_plan=true
+        fi
+
+        echo -e "${BOLD}Loki Mode v$version - Repo improvement${NC}"
+        echo ""
+        echo -e "${CYAN}Repo:${NC} $LOKI_REPO_TARGET"
+        if [ "$repo_depth" = "fast" ]; then
+            echo -e "${DIM}Loki will inspect this project, pick one high-value improvement,${NC}"
+            echo -e "${DIM}implement it, and test it.${NC}"
+            echo -e "${DIM}Fast pass: $_repo_max_iter iterations max, simple tier, council and${NC}"
+            echo -e "${DIM}heavy phases OFF. Reduced gates: you get measured run evidence${NC}"
+            echo -e "${DIM}(diffs, cost, time), NOT a council-verified verdict.${NC}"
+            echo -e "${DIM}Run full verification with: loki start \"$LOKI_REPO_TARGET\" --full${NC}"
+        else
+            echo -e "${DIM}Loki will inspect this project, pick one high-value improvement,${NC}"
+            echo -e "${DIM}implement it, test it, and produce verified evidence.${NC}"
+            echo -e "${DIM}Full depth: quality gates and completion council stay ON.${NC}"
+        fi
+        echo -e "${DIM}Scope it yourself instead with: loki start \"<what you want>\".${NC}"
+        echo ""
+    fi
+
     # R7: existing-repo no-arg path also gets the TTFV "what next" framing at the
     # end of the run. Execution here is UNCHANGED (full-depth no-PRD codebase
     # analysis + generated-PRD-reuse); we only add accurate end-of-run framing.
     # The signal value ("repo") drives the full-depth wording in run.sh so the
     # message does not falsely claim a lightweight pass.
-    if [ "$detected_type" = "empty" ] && [ -z "${LOKI_TTFV:-}" ]; then
+    if { [ "$detected_type" = "empty" ] || [ "$detected_type" = "repo" ]; } \
+       && [ -z "${LOKI_TTFV:-}" ]; then
         export LOKI_TTFV=repo
     fi
 
@@ -6307,6 +6579,34 @@ else
     DASHBOARD_DEFAULT_HOST="127.0.0.1"
 fi
 
+# EXPOSED BIND REQUIRES AUTH (issue #188).
+#
+# dashboard/auth.py:788 returns True -- allow -- when neither LOKI_ENTERPRISE_AUTH
+# nor OIDC is configured. That makes all 166 Depends(require_scope) endpoints
+# open. On loopback that is defensible: the trust boundary is the machine.
+# Bound to 0.0.0.0 it is not, and NEITHER the Dockerfile NOR the Helm chart set
+# any auth env, so an operator following the shipped chart gets an
+# unauthenticated dashboard on every interface without choosing it.
+#
+# Refuses to start rather than auto-minting a token. An auto-token an operator
+# never sees is worse than a refusal: they believe they are protected, and the
+# credential is sitting in a container they did not know to guard. A refusal is
+# loud, happens at deploy time rather than after exposure, and names the fix.
+#
+# LOKI_DASHBOARD_ALLOW_INSECURE_BIND=1 is the deliberate override, for a cluster
+# whose network policy already bounds ingress. Named so it appears in a diff and
+# a reviewer can ask why it is set.
+_loki_dashboard_bind_is_safe() {
+    local _host="${1:-}"
+    case "$_host" in
+        127.0.0.1|localhost|::1|"") return 0 ;;
+    esac
+    [ "${LOKI_DASHBOARD_ALLOW_INSECURE_BIND:-}" = "1" ] && return 0
+    [ "${LOKI_ENTERPRISE_AUTH:-}" = "true" ] || [ "${LOKI_ENTERPRISE_AUTH:-}" = "1" ] && return 0
+    [ -n "${LOKI_OIDC_ISSUER:-}" ] && [ -n "${LOKI_OIDC_CLIENT_ID:-}" ] && return 0
+    return 1
+}
+
 cmd_dashboard() {
     local subcommand="${1:-}"
 
@@ -6461,6 +6761,23 @@ cmd_dashboard_start() {
         esac
     done
 
+    # Refuse an exposed bind with auth disabled (issue #188). Checked AFTER
+    # argument parsing so an explicit --host is covered, not just the default.
+    if ! _loki_dashboard_bind_is_safe "$host"; then
+        echo -e "${RED}Refusing to start: binding $host with authentication disabled.${NC}" >&2
+        echo "" >&2
+        echo "  Every dashboard endpoint would be reachable on all interfaces with no" >&2
+        echo "  credential. dashboard/auth.py allows all requests when neither" >&2
+        echo "  LOKI_ENTERPRISE_AUTH nor OIDC is configured." >&2
+        echo "" >&2
+        echo "  Pick one:" >&2
+        echo "    LOKI_ENTERPRISE_AUTH=true          enable token auth (loki dashboard token create)" >&2
+        echo "    LOKI_OIDC_ISSUER + _CLIENT_ID      enable OIDC" >&2
+        echo "    --host 127.0.0.1                   bind loopback only" >&2
+        echo "    LOKI_DASHBOARD_ALLOW_INSECURE_BIND=1   accept the exposure deliberately" >&2
+        exit 2
+    fi
+
     # Validate port is numeric
     if [[ ! "$port" =~ ^[0-9]+$ ]]; then
         echo -e "${RED}Invalid port: $port${NC}"
@@ -14795,6 +15112,51 @@ $brief_text
 BRIEFEOF
 }
 
+# Build a bounded input for `loki start <repo-directory>`. This intentionally
+# contains no caller-controlled path: repository identity comes from cwd, while
+# the task remains stable, reviewable, and safe to render into a prompt.
+#
+# The trailing Mode line is the only variable part, and it must match what the
+# run actually does: a fast pass runs with the council off, so a PRD telling the
+# agent it is under "full verification" would be a false claim in the prompt
+# itself. The body stays a quoted heredoc (no expansion, nothing injectable);
+# the Mode line is appended from a fixed string chosen by a validated depth.
+# Usage: synthesize_repo_prd <output_file> [full|fast]
+synthesize_repo_prd() {
+    local out_file="$1"
+    local depth="${2:-full}"
+    mkdir -p "$(dirname "$out_file")" 2>/dev/null || true
+    cat > "$out_file" <<'REPOEOF'
+# Existing Repository Improvement
+
+## Outcome
+Inspect this repository's instructions, product signals, and current tests.
+Select one small, high-value user-facing improvement and implement it completely.
+
+## Success Criteria
+- The improvement has a clear user outcome and a bounded diff.
+- Focused tests or checks prove the changed behavior.
+- Existing unrelated work is preserved.
+- Loki's normal outcome evidence identifies what changed and what passed.
+
+## Constraints
+- Make one coherent improvement, not a broad rewrite.
+- Reuse the repository's established architecture and dependencies.
+- Keep the change easy to review and roll back.
+- Do not claim deployment, adoption, or customer value without evidence.
+REPOEOF
+    if [ "$depth" = "fast" ]; then
+        printf '%s\n' \
+            "- This is a fast, capped pass. Keep the change small enough to finish and prove." \
+            "" \
+            "**Mode:** Existing repository improvement (fast pass, reduced gates)." \
+            "The completion council and heavy review phases are OFF on this run." \
+            "Do not describe the result as council-verified or fully verified." >> "$out_file"
+    else
+        printf '\n**Mode:** Existing repository improvement (full verification)\n' >> "$out_file"
+    fi
+}
+
 # Quick mode - lightweight single-task execution
 cmd_quick() {
     # v7.6.3 B-11 fix: --help previously fell through to provider invocation
@@ -34878,6 +35240,13 @@ cmd_proof() {
             echo "  show <id>            Pretty-print .loki/proofs/<id>/proof.json"
             echo "  verify <id>          Re-check a receipt against the repo (tamper + drift);"
             echo "                       exit 0 clean, 1 tamper/drift. Verify it yourself."
+            echo ""
+            echo "Options for 'verify':"
+            echo "  --human              Render the verdict and every failure reason as prose"
+            echo "  --jwks <url|file>    Also check the receipt's attestation against a published"
+            echo "                       key set. Accepts a server URL or a local jwks.json, so a"
+            echo "                       third party can check WHO produced a receipt with no API"
+            echo "                       token, no gpg key import, and no network."
             echo "  md <id>              Paste-able Markdown for a PR comment or Slack
   open <id>            Open .loki/proofs/<id>/index.html in a browser"
             echo "  share <id>           Publish the proof page as a GitHub Gist (opt-in)"
@@ -35093,14 +35462,31 @@ PYEOF
             # stdout verbatim, are unaffected. The flag is STRIPPED from the
             # positional args rather than assumed at a fixed index, so it works
             # before or after the id.
-            local _pv_human=0 _pv_args=()
-            local _pv_a
+            # --jwks <url-or-file> additionally checks the receipt's
+            # attestation against a published key set. This is the third-party
+            # path: an auditor who was handed a proof.json can check WHO
+            # produced it without running a build, without our API token, and
+            # without importing a gpg key. A FILE is accepted as well as a URL
+            # so an air-gapped reviewer, handed the receipt and the key set on
+            # disk, can still verify -- requiring the network would exclude
+            # exactly the reviewer who most needs this.
+            local _pv_human=0 _pv_jwks="" _pv_args=()
+            local _pv_a _pv_want_jwks=0
             for _pv_a in "$@"; do
+                if [ "$_pv_want_jwks" -eq 1 ]; then
+                    _pv_jwks="$_pv_a"; _pv_want_jwks=0; continue
+                fi
                 case "$_pv_a" in
                     --human) _pv_human=1 ;;
+                    --jwks) _pv_want_jwks=1 ;;
+                    --jwks=*) _pv_jwks="${_pv_a#--jwks=}" ;;
                     *) _pv_args+=("$_pv_a") ;;
                 esac
             done
+            if [ "$_pv_want_jwks" -eq 1 ]; then
+                echo -e "${RED}--jwks needs a URL or file path.${NC}" >&2
+                exit 2
+            fi
             set -- "${_pv_args[@]+"${_pv_args[@]}"}"
 
             local id="${1:-}"
@@ -35121,12 +35507,53 @@ PYEOF
                 echo -e "${RED}Verifier not found (autonomy/lib/proof-verify.py).${NC}"
                 exit 2
             fi
+            # `|| _pv_rc=$?` is load-bearing: this script runs under `set -e`
+            # (loki:22), so a bare call to a verifier that exits 1 on drift --
+            # its NORMAL result -- aborts the whole command before the exit
+            # status can be read. Without the guard the attestation block below
+            # is unreachable on exactly the receipts it exists to check.
+            local _pv_rc=0
             if [ "$_pv_human" -eq 1 ]; then
-                python3 "$verifier" --human "$pj" "${TARGET_DIR:-.}"
+                python3 "$verifier" --human "$pj" "${TARGET_DIR:-.}" || _pv_rc=$?
             else
-                python3 "$verifier" "$pj" "${TARGET_DIR:-.}"
+                python3 "$verifier" "$pj" "${TARGET_DIR:-.}" || _pv_rc=$?
+            fi
+
+            # The attestation check runs AFTER, and can only make the verdict
+            # worse, never better. A valid attestation does not excuse a failed
+            # integrity hash: the signature proves who produced the bytes, not
+            # that the bytes are internally consistent. Folding the two together
+            # would let a signed-but-tampered receipt exit 0.
+            if [ -n "$_pv_jwks" ]; then
+                local _pv_att
+                _pv_att="$(loki_proof_attestation_check "$pj" "$_pv_jwks")"
+                case "$_pv_att" in
+                    ok)
+                        echo "attestation: VERIFIED against ${_pv_jwks}" >&2
+                        echo "  Proven: these bytes were signed by the holder of a key in that set." >&2
+                        echo "  NOT proven: that the code is correct. A receipt records which checks ran." >&2
+                        ;;
+                    bad)
+                        echo -e "${RED}attestation: FAILED -- the token does not cover these bytes.${NC}" >&2
+                        echo "  Either the receipt was altered after signing, or the attestation" >&2
+                        echo "  belongs to a different run. Do not trust this receipt." >&2
+                        _pv_rc=1
+                        ;;
+                    none)
+                        echo -e "${YELLOW}attestation: ABSENT -- this receipt carries no attestation.${NC}" >&2
+                        echo "  Nothing was checked against ${_pv_jwks}. The receipt may still be" >&2
+                        echo "  gpg-signed; this says only that it has no JWKS attestation." >&2
+                        ;;
+                    *)
+                        # Unreachable key set, unreadable file, missing python
+                        # deps. NOT a verdict: an absent measurement must never
+                        # read as either a pass or an accusation.
+                        echo -e "${YELLOW}attestation: NOT CHECKED -- could not read a key set from ${_pv_jwks}.${NC}" >&2
+                        echo "  This is not a failure of the receipt. Nothing was proven either way." >&2
+                        ;;
+                esac
             fi
-            exit $?
+            exit "$_pv_rc"
             ;;
         open)
             local id="${1:-}"