loki-mode 7.114.0 → 7.115.0

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 v7.114.0
+# Loki Mode v7.115.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -408,4 +408,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.114.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.115.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.114.0
+7.115.0

package/autonomy/lib/effort_estimator.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+"""Engineering-hours estimator for the per-build proof.json (Rank 6).
+
+Replaces the naive "iterations x 15min" number (which is blind to the actual
+work) with a WORK-based estimate: it reads the real signals available at
+proof-generation time -- the git diff stat (insertions / deletions / files
+changed), the number of files touched, whether tests were written, and the
+task/PRD scope -- and predicts the equivalent human-engineering-hours plus a
+low/high band.
+
+Two methods, chosen HONESTLY at runtime:
+
+  method="llm"       An LLM was available AND returned a parseable number. The
+                     model id is recorded. Gated behind LOKI_EFFORT_LLM=1 so a
+                     model is NEVER called on every build by default (cost /
+                     latency / the 30s proof cap). Any failure -- no key, no
+                     CLI, timeout, unparseable output -- FAILS OPEN to the
+                     heuristic. We never emit method="llm" with a number the
+                     model did not actually give us.
+
+  method="heuristic" The deterministic work-based fallback. Same inputs, a
+                     fixed formula, reproducible for identical inputs. This is
+                     the default path (and the only path in headless CI /
+                     offline). Labeled uncalibrated -- see `calibrated` below.
+
+The estimate is ALWAYS labeled calibrated=false ("uncalibrated") in this lane:
+no ground-truth engineer-hour dataset has scored it yet, so the number is a
+transparent estimate, never presented as validated. A separate calibration
+harness may flip that once an error metric clears a threshold.
+
+inputs_hash: sha256 over the canonical inputs (diff stat + files + tests +
+scope). Identical whether the method is llm or heuristic, so the estimate is
+reproducible and auditable -- a reader can recompute the hash from the same
+proof and confirm the estimator saw exactly these inputs.
+
+This module is import-only and never raises to the caller: estimate() catches
+everything and falls open to the heuristic (and, in the worst case, a zeroed
+estimate) so proof.json generation can never be broken by it.
+"""
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+
+
+# Schema of the emitted effort_estimate object. Bumped if the shape changes so
+# a reader can tell which estimator produced a given field set.
+ESTIMATOR_VERSION = "1"
+
+# The brief is stored truncated to this many chars in proof.json (matches
+# proof-generator.generate()'s brief[:600]); the hashed brief_len is capped to
+# the same bound so inputs_hash is recomputable from the written receipt.
+_BRIEF_HASH_CAP = 600
+
+
+def _canonical(obj):
+    """Stable JSON serialization for hashing (sorted keys, compact)."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False)
+
+
+def _to_int(v, default=0):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return default
+
+
+def _canonical_inputs(files_changed, tests, spec, iterations):
+    """The exact inputs the estimate is a function of, in a canonical shape.
+
+    Only work signals -- NOT wall-clock or cost, which are noisy and would make
+    the hash non-reproducible across machines. Iteration count is carried as a
+    weak secondary signal (it slightly widens the band) but is deliberately not
+    the primary driver: the backlog AC requires the estimate reflect real work,
+    not iteration count alone.
+    """
+    fc = files_changed or {}
+    files = fc.get("files") or []
+    t = tests or {}
+    sp = spec or {}
+    it = iterations or {}
+    return {
+        "diff": {
+            "count": _to_int(fc.get("count")),
+            "insertions": _to_int(fc.get("insertions")),
+            "deletions": _to_int(fc.get("deletions")),
+            # Sorted file paths so ordering never perturbs the hash.
+            "files": sorted(
+                str(f.get("path", "")) for f in files if isinstance(f, dict)
+            ),
+        },
+        "tests": {
+            "status": str(t.get("status") or "not_run"),
+            "passed_count": _to_int(t.get("passed_count")),
+            "failed_count": _to_int(t.get("failed_count")),
+        },
+        "scope": {
+            # NOTE: the raw spec source is a filesystem PATH (e.g. an absolute
+            # path into the build's temp dir), which is build-location noise, NOT
+            # a work signal -- hashing it would make identical work produce
+            # different hashes across machines/dirs. We hash only whether a spec
+            # was present, plus the brief length (a real proxy for scope size).
+            # The full brief text is not hashed (brittle to whitespace edits).
+            "has_spec": bool(str(sp.get("source") or "")
+                             not in ("", "codebase-analysis")),
+            # Cap the hashed length at the SAME 600-char bound the generator
+            # applies to spec.brief before writing proof.json (generate() does
+            # brief[:600] after the estimate is computed). Without this cap, a
+            # brief longer than 600 chars would hash the full length while the
+            # receipt stores only 600, so a third party recomputing inputs_hash
+            # from the written proof.json would get a different value -- the hash
+            # would be self-consistent but NOT reproducible from the artifact,
+            # defeating the auditability the hash exists for.
+            "brief_len": min(len(str(sp.get("brief") or "")), _BRIEF_HASH_CAP),
+        },
+        "iterations": _to_int(it.get("count")),
+    }
+
+
+def _inputs_hash(canon_inputs):
+    return hashlib.sha256(
+        _canonical(canon_inputs).encode("utf-8")
+    ).hexdigest()
+
+
+def heuristic_estimate(canon_inputs):
+    """Deterministic WORK-based hours from the canonical inputs.
+
+    Model (transparent + reproducible):
+      - A baseline per changed file (reading, wiring, context switching).
+      - A per-line component on net churn (insertions + deletions), the bulk of
+        the signal, scaled to a rough "lines of considered code per hour".
+      - A test bonus: writing tests is real engineering effort the line count
+        alone under-counts.
+      - A scope bonus from the PRD/brief size (bigger specs = more design).
+
+    Returns (hours, low, high) rounded to 2 decimals. The band is a fixed
+    +/- fraction, slightly widened by iteration count (more back-and-forth =
+    more uncertainty). Every constant is a stated assumption, NOT a calibrated
+    value -- hence the estimate is always labeled uncalibrated.
+    """
+    diff = canon_inputs.get("diff", {})
+    files = diff.get("files", []) or []
+    n_files = _to_int(diff.get("count")) or len(files)
+    churn = _to_int(diff.get("insertions")) + _to_int(diff.get("deletions"))
+
+    # Test signal: from the tests block AND from test-looking changed files.
+    tests = canon_inputs.get("tests", {})
+    test_files = 0
+    for p in files:
+        pl = str(p).lower()
+        if any(kw in pl for kw in
+               ("test", "spec", ".test.", ".spec.", "_test.", "_spec.")):
+            test_files += 1
+    tests_ran = str(tests.get("status")) in ("verified", "failed", "passed")
+
+    # --- constants (assumptions, uncalibrated) ---
+    PER_FILE_HOURS = 0.15          # ~9 min of context per file touched
+    LINES_PER_HOUR = 40.0          # considered (not typed) lines per hour
+    TEST_FILE_BONUS_HOURS = 0.35   # writing a test file is real effort
+    TESTS_RAN_BONUS_HOURS = 0.25   # having a runnable, green/red suite at all
+    SCOPE_HOURS_PER_1K_CHARS = 0.5  # design time scaling with brief size
+
+    hours = 0.0
+    hours += n_files * PER_FILE_HOURS
+    hours += (churn / LINES_PER_HOUR) if churn > 0 else 0.0
+    hours += test_files * TEST_FILE_BONUS_HOURS
+    if tests_ran:
+        hours += TESTS_RAN_BONUS_HOURS
+    brief_len = _to_int((canon_inputs.get("scope") or {}).get("brief_len"))
+    hours += (brief_len / 1000.0) * SCOPE_HOURS_PER_1K_CHARS
+
+    # A build that changed nothing is genuinely ~0 human-hours; do not invent
+    # effort from a bare iteration count.
+    if n_files == 0 and churn == 0:
+        hours = 0.0
+
+    hours = round(hours, 2)
+
+    # Band: +/- 40% base, widened up to +20% more by iteration churn.
+    iters = _to_int(canon_inputs.get("iterations"))
+    widen = min(iters * 0.02, 0.20)
+    low = round(hours * (1.0 - min(0.40 + widen, 0.75)), 2)
+    high = round(hours * (1.0 + 0.40 + widen), 2)
+    if low < 0:
+        low = 0.0
+    return hours, low, high
+
+
+_HOURS_RE = re.compile(r"(-?\d+(?:\.\d+)?)")
+
+
+def _parse_llm_hours(text):
+    """Extract (hours, low, high) from an LLM completion, or None.
+
+    Accepts a JSON object {"hours":..,"low":..,"high":..} anywhere in the
+    output (preferred), else falls back to the first number as hours. Returns
+    None on anything unparseable so the caller fails open. NEVER guesses a band
+    it was not given: if only hours is found, low/high are derived as a fixed
+    band around it (and the method is still honestly "llm" -- the CENTRAL number
+    came from the model)."""
+    if not text or not str(text).strip():
+        return None
+    s = str(text)
+    # Prefer an embedded JSON object.
+    for m in re.finditer(r"\{[^{}]*\}", s):
+        try:
+            obj = json.loads(m.group(0))
+        except Exception:
+            continue
+        if isinstance(obj, dict) and "hours" in obj:
+            try:
+                h = float(obj["hours"])
+            except (TypeError, ValueError):
+                continue
+            if h < 0:
+                continue
+            low = obj.get("low")
+            high = obj.get("high")
+            try:
+                low = float(low) if low is not None else round(h * 0.6, 2)
+            except (TypeError, ValueError):
+                low = round(h * 0.6, 2)
+            try:
+                high = float(high) if high is not None else round(h * 1.4, 2)
+            except (TypeError, ValueError):
+                high = round(h * 1.4, 2)
+            return round(h, 2), round(low, 2), round(high, 2)
+    # Fallback: first bare number in the text.
+    m = _HOURS_RE.search(s)
+    if m:
+        try:
+            h = float(m.group(1))
+        except ValueError:
+            return None
+        if h < 0:
+            return None
+        return round(h, 2), round(h * 0.6, 2), round(h * 1.4, 2)
+    return None
+
+
+def _llm_estimate(canon_inputs, timeout=18):
+    """Try an LLM estimate. Returns (hours, low, high, model) or None.
+
+    Gated behind LOKI_EFFORT_LLM=1 so a model is never invoked on every build.
+    Honors LOKI_EFFORT_LLM_STUB (its OWN stub env, NOT the wiki one) for
+    deterministic tests: a file path or literal completion string. Any failure
+    returns None -> caller falls open to the heuristic.
+    """
+    if os.environ.get("LOKI_EFFORT_LLM", "") not in ("1", "true", "yes", "on"):
+        return None
+
+    prompt = _build_prompt(canon_inputs)
+
+    stub = os.environ.get("LOKI_EFFORT_LLM_STUB")
+    if stub is not None:
+        completion = _read_stub(stub)
+        model = os.environ.get("LOKI_EFFORT_LLM_MODEL", "stub")
+        parsed = _parse_llm_hours(completion)
+        if parsed is None:
+            return None
+        h, low, high = parsed
+        return h, low, high, model
+
+    provider = os.environ.get("LOKI_PROVIDER", "claude")
+    cmds = {
+        "claude": ["claude", "-p", prompt],
+        "codex": ["codex", "exec", "--sandbox", "read-only", prompt],
+        "cline": ["cline", "-y", prompt],
+        "aider": ["aider", "--message", prompt, "--yes-always",
+                  "--no-auto-commits"],
+    }
+    base = cmds.get(provider)
+    if base is None or not _which(base[0]):
+        return None
+    model = os.environ.get("SESSION_MODEL") or provider
+    try:
+        out = subprocess.run(
+            base, capture_output=True, text=True, timeout=timeout,
+            stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0 and not (out.stdout or "").strip():
+        return None
+    parsed = _parse_llm_hours(out.stdout)
+    if parsed is None:
+        return None
+    h, low, high = parsed
+    return h, low, high, model
+
+
+def _build_prompt(canon_inputs):
+    diff = canon_inputs.get("diff", {})
+    return (
+        "You are estimating how many hours a competent human software engineer "
+        "would take to produce EXACTLY this change, from scratch, including "
+        "design, implementation, and testing. Respond with ONLY a JSON object "
+        "of the form {\"hours\": <number>, \"low\": <number>, \"high\": "
+        "<number>} and nothing else.\n\n"
+        "Change signals:\n"
+        "- files changed: %d\n"
+        "- lines inserted: %d\n"
+        "- lines deleted: %d\n"
+        "- test status: %s\n"
+        "- scope brief length (chars): %d\n"
+        % (
+            _to_int(diff.get("count")),
+            _to_int(diff.get("insertions")),
+            _to_int(diff.get("deletions")),
+            str((canon_inputs.get("tests") or {}).get("status")),
+            _to_int((canon_inputs.get("scope") or {}).get("brief_len")),
+        )
+    )
+
+
+def _read_stub(stub):
+    if os.path.sep in stub or stub.endswith(".txt") or stub.endswith(".json"):
+        if os.path.isfile(stub):
+            try:
+                with open(stub, encoding="utf-8", errors="replace") as f:
+                    return f.read()
+            except OSError:
+                return ""
+    return stub
+
+
+def _which(name):
+    for d in os.environ.get("PATH", "").split(os.pathsep):
+        cand = os.path.join(d, name)
+        if os.path.isfile(cand) and os.access(cand, os.X_OK):
+            return cand
+    return None
+
+
+def estimate(files_changed, tests, spec, iterations):
+    """Return the effort_estimate object for proof.json. Never raises.
+
+    Shape:
+      {
+        hours, low, high,               # equivalent human-engineering-hours
+        method: "llm" | "heuristic",
+        model,                          # model id on the llm path, else ""
+        inputs_hash,                    # sha256 over the canonical inputs
+        calibrated,                     # always False in this lane
+        label,                          # human-facing honesty label
+        estimator_version,
+      }
+    """
+    try:
+        canon = _canonical_inputs(files_changed, tests, spec, iterations)
+    except Exception:
+        canon = {"diff": {"count": 0, "insertions": 0, "deletions": 0,
+                          "files": []}, "tests": {}, "scope": {},
+                 "iterations": 0}
+    try:
+        ihash = _inputs_hash(canon)
+    except Exception:
+        ihash = ""
+
+    method = "heuristic"
+    model = ""
+    hours = low = high = 0.0
+
+    # LLM path first (opt-in); fail open to heuristic on ANY problem.
+    try:
+        llm = _llm_estimate(canon)
+    except Exception:
+        llm = None
+    if llm is not None:
+        hours, low, high, model = llm
+        method = "llm"
+    else:
+        try:
+            hours, low, high = heuristic_estimate(canon)
+        except Exception:
+            hours, low, high = 0.0, 0.0, 0.0
+        method = "heuristic"
+        model = ""
+
+    label = (
+        "estimated (uncalibrated, %s)" % method
+    )
+    return {
+        "hours": hours,
+        "low": low,
+        "high": high,
+        "method": method,
+        "model": model,
+        "inputs_hash": ihash,
+        "calibrated": False,
+        "label": label,
+        "estimator_version": ESTIMATOR_VERSION,
+    }

package/autonomy/lib/proof-generator.py

@@ -36,6 +36,7 @@ if _HERE not in sys.path:
 
 import proof_redact  # noqa: E402
 from efficiency_cost import collect_efficiency as _collect_efficiency  # noqa: E402
+import effort_estimator  # noqa: E402
 
 
 # ---------------------------------------------------------------------------
@@ -741,6 +742,25 @@ def _build_proof(args, loki_dir, target_dir, repo_root):
         "evidence_gate": evidence_gate,
     }
 
+    # Effort estimate (Rank 6): equivalent human-engineering-hours for this
+    # build, from the REAL work signals (diff stat + files + tests + scope), NOT
+    # the iteration count alone. Emitted as a TOP-LEVEL additive key on purpose:
+    # it is an ESTIMATE (an opinion, LLM on the opt-in path), so it must never
+    # sit under `facts` where _compute_headline/_compute_degraded could let it
+    # leak into the deterministic VERIFIED headline. Fail-open: never raises,
+    # defaults to the deterministic heuristic when no model is available.
+    try:
+        effort_estimate = effort_estimator.estimate(
+            files_changed, tests, spec, iterations
+        )
+    except Exception:
+        effort_estimate = {
+            "hours": 0.0, "low": 0.0, "high": 0.0,
+            "method": "heuristic", "model": "", "inputs_hash": "",
+            "calibrated": False, "label": "estimated (uncalibrated, heuristic)",
+            "estimator_version": effort_estimator.ESTIMATOR_VERSION,
+        }
+
     # Assemble WITHOUT redaction / verification fields (advisor ordering).
     # Top-level flat keys are RETAINED as a back-compat mirror so existing
     # dashboard/CLI/template readers (schema v1.0 consumers) keep working; the
@@ -761,6 +781,8 @@ def _build_proof(args, loki_dir, target_dir, repo_root):
         "quality_gates": quality_gates,
         "cost": cost,
         "deployment": deployment,
+        # Rank 6: work-based engineering-hours estimate (top-level, NOT a fact).
+        "effort_estimate": effort_estimate,
         # v1.1 evidence model (additive).
         "facts": facts,
         "assessments": assessments,

package/autonomy/verify.sh

@@ -170,6 +170,71 @@ verify_diff_base() {
     return 0
 }
 
+# ---------------------------------------------------------------------------
+# Code-scope / locality record (rank 10, ADVISORY-FIRST).
+#
+# Turns the already-computed VERIFY_DIFF_FILES / VERIFY_DIFF_INS / VERIFY_DIFF_DEL
+# into a structured scope record: {files_changed, net_lines, verdict, thresholds}.
+# net_lines is line GROWTH (insertions - deletions), matching "net line growth" --
+# it goes negative on deletion-heavy diffs (only growth trips a threshold).
+#
+# ADVISORY BY DEFAULT. The verdict is a LABEL in the record only; this helper does
+# NOT emit a gate row and does NOT feed verify_compute_verdict, so it can never
+# change the exit code or block a build (the friction-regression guard, and the
+# greenfield byte-identity guarantee -- loki start never reaches verify_main).
+#
+# Thresholds:
+#   - Soft thresholds (LOKI_SCOPE_SOFT_FILES / LOKI_SCOPE_SOFT_NET_LINES) have sane
+#     defaults; exceeding a soft threshold with NO hard cap set -> verdict "warn".
+#   - Hard caps (LOKI_SCOPE_MAX_FILES / LOKI_SCOPE_MAX_NET_LINES) are OPT-IN: only
+#     when such an env var is EXPLICITLY SET and exceeded does the verdict become
+#     "block". Even then this record does not by itself block the build; it is the
+#     opt-in signal a consumer/enforcer can act on.
+#   - Under all applicable thresholds -> "ok".
+#
+# Sets globals: VERIFY_SCOPE_FILES VERIFY_SCOPE_NET_LINES VERIFY_SCOPE_VERDICT
+#               VERIFY_SCOPE_SOFT_FILES VERIFY_SCOPE_SOFT_NET_LINES
+#               VERIFY_SCOPE_MAX_FILES VERIFY_SCOPE_MAX_NET_LINES (empty when unset)
+# ---------------------------------------------------------------------------
+verify_scope_record() {
+    local files="${VERIFY_DIFF_FILES:-0}"
+    local ins="${VERIFY_DIFF_INS:-0}"
+    local del="${VERIFY_DIFF_DEL:-0}"
+    local net=$(( ins - del ))
+
+    # Soft advisory thresholds (defaults; overridable).
+    local soft_files="${LOKI_SCOPE_SOFT_FILES:-25}"
+    local soft_net="${LOKI_SCOPE_SOFT_NET_LINES:-500}"
+    # Hard caps are opt-in: unset means "never block".
+    local max_files="${LOKI_SCOPE_MAX_FILES:-}"
+    local max_net="${LOKI_SCOPE_MAX_NET_LINES:-}"
+
+    local verdict="ok"
+
+    # Hard-cap check first (only when explicitly set) -> "block".
+    if [ -n "$max_files" ] && [ "$files" -gt "$max_files" ] 2>/dev/null; then
+        verdict="block"
+    elif [ -n "$max_net" ] && [ "$net" -gt "$max_net" ] 2>/dev/null; then
+        verdict="block"
+    # Soft threshold (advisory, no hard cap tripped) -> "warn".
+    elif [ "$files" -gt "$soft_files" ] 2>/dev/null; then
+        verdict="warn"
+    elif [ "$net" -gt "$soft_net" ] 2>/dev/null; then
+        verdict="warn"
+    fi
+
+    VERIFY_SCOPE_FILES="$files"
+    VERIFY_SCOPE_NET_LINES="$net"
+    VERIFY_SCOPE_VERDICT="$verdict"
+    VERIFY_SCOPE_SOFT_FILES="$soft_files"
+    VERIFY_SCOPE_SOFT_NET_LINES="$soft_net"
+    VERIFY_SCOPE_MAX_FILES="$max_files"
+    VERIFY_SCOPE_MAX_NET_LINES="$max_net"
+
+    _verify_log "scope: $files files, net $net lines -> $verdict (soft $soft_files/$soft_net, hard ${max_files:-unset}/${max_net:-unset})"
+    return 0
+}
+
 # ---------------------------------------------------------------------------
 # Gate: build (faithful extension of run.sh language detection).
 #
@@ -916,6 +981,100 @@ PYEOF
     return 0
 }
 
+# ---------------------------------------------------------------------------
+# Setup-recipe WRITER (rank 7). Writes .loki/setup-recipe.json after a VERIFIED
+# runtime boot, capturing the deterministic steps to reach a runnable state so
+# later verify/e2e runs replay the recipe instead of re-detecting heuristically
+# (the CONSUMER already exists in _verify_runtime_detect: it reads "start"/"port").
+#
+# Keys: {install, seed, env_keys, start, health_path, port}.
+#   - env_keys are env var NAMES ONLY, harvested from .env.example / .env in the
+#     tree (left side of `NAME=value`). SECRET VALUES ARE NEVER PERSISTED.
+#   - install/seed are best-effort deterministic detections (npm ci / pip install
+#     / go mod download; a seed script when present). Empty string when unknown.
+#
+# Best effort and fail-open: any failure leaves no recipe and never changes the
+# gate outcome. Called ONLY from the boot-pass branch, so a failed boot writes
+# nothing.
+#
+# Args: $1 tree  $2 start_command  $3 port  $4 health_path
+# ---------------------------------------------------------------------------
+_verify_write_setup_recipe() {
+    local tree="$1" start="$2" port="$3" health_path="$4"
+    command -v python3 >/dev/null 2>&1 || return 0
+    [ -d "$tree" ] || return 0
+
+    # Detect a deterministic install command from the tree (best effort).
+    local install=""
+    if [ -f "$tree/package-lock.json" ]; then
+        install="npm ci"
+    elif [ -f "$tree/package.json" ]; then
+        install="npm install"
+    elif [ -f "$tree/requirements.txt" ]; then
+        install="pip install -r requirements.txt"
+    elif [ -f "$tree/go.mod" ]; then
+        install="go mod download"
+    elif [ -f "$tree/Cargo.toml" ]; then
+        install="cargo fetch"
+    fi
+
+    # Detect a seed step (best effort): package.json "seed" script, else empty.
+    local seed=""
+    if [ -f "$tree/package.json" ] && grep -q '"seed"[[:space:]]*:' "$tree/package.json" 2>/dev/null; then
+        seed="npm run seed"
+    fi
+
+    # Harvest env var NAMES only from .env.example / .env (never the values).
+    # The python writer parses these; we hand it the file paths that exist.
+    local env_src=""
+    [ -f "$tree/.env.example" ] && env_src="$tree/.env.example"
+    [ -z "$env_src" ] && [ -f "$tree/.env" ] && env_src="$tree/.env"
+
+    _SR_DIR="$tree/.loki" _SR_INSTALL="$install" _SR_SEED="$seed" \
+    _SR_START="$start" _SR_HEALTH="$health_path" _SR_PORT="$port" \
+    _SR_ENVSRC="$env_src" \
+    python3 - <<'PYEOF' 2>/dev/null || return 0
+import json, os, re
+
+out_dir = os.environ["_SR_DIR"]
+
+# env_keys: NAMES ONLY. Parse KEY=VALUE / export KEY=VALUE lines, keep the KEY.
+# The value side is never read into the recipe (security AC).
+env_keys = []
+src = os.environ.get("_SR_ENVSRC") or ""
+if src and os.path.exists(src):
+    seen = set()
+    try:
+        with open(src) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                name = line.split("=", 1)[0].strip()
+                name = re.sub(r"^export\s+", "", name)
+                if re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name) and name not in seen:
+                    seen.add(name)
+                    env_keys.append(name)
+    except Exception:
+        env_keys = []
+
+recipe = {
+    "install": os.environ.get("_SR_INSTALL", ""),
+    "seed": os.environ.get("_SR_SEED", ""),
+    "env_keys": env_keys,
+    "start": os.environ.get("_SR_START", ""),
+    "health_path": os.environ.get("_SR_HEALTH", "") or "/",
+    "port": os.environ.get("_SR_PORT", ""),
+}
+
+os.makedirs(out_dir, exist_ok=True)
+with open(os.path.join(out_dir, "setup-recipe.json"), "w") as f:
+    json.dump(recipe, f, indent=2)
+    f.write("\n")
+PYEOF
+    return 0
+}
+
 verify_gate_runtime() {
     local tree="$1"
     # Opt-out (default on). Disabled -> emit no row -> byte-identical.
@@ -1055,6 +1214,11 @@ verify_gate_runtime() {
             "Runtime boot smoke failed: '$method' booted but returned HTTP $http_status on $url (server error)."
     else
         _verify_add_gate "runtime" "pass" "boot" "$summary" "true"
+        # Setup-recipe WRITER (rank 7). Only on a VERIFIED boot (2xx/3xx/4xx):
+        # persist a deterministic .loki/setup-recipe.json that the runtime
+        # detector (_verify_runtime_detect) consumes first on later runs. Env var
+        # NAMES only, never secret VALUES. Best effort; never changes the verdict.
+        _verify_write_setup_recipe "$tree" "$method" "$probe_port" "$health_path" || true
     fi
 
     # Record a structured runtime artifact alongside the gate row so the boot is
@@ -1339,6 +1503,13 @@ verify_emit_evidence() {
     _V_BLOCKON="$block_on" \
     _V_LEDGER_SHA="${_VERIFY_EXPECT_LEDGER_SHA:-}" \
     _V_LEDGER_HASHOK="${_VERIFY_EXPECT_LEDGER_HASH_OK:-}" \
+    _V_SCOPE_FILES="${VERIFY_SCOPE_FILES:-}" \
+    _V_SCOPE_NET="${VERIFY_SCOPE_NET_LINES:-}" \
+    _V_SCOPE_VERDICT="${VERIFY_SCOPE_VERDICT:-}" \
+    _V_SCOPE_SOFT_FILES="${VERIFY_SCOPE_SOFT_FILES:-}" \
+    _V_SCOPE_SOFT_NET="${VERIFY_SCOPE_SOFT_NET_LINES:-}" \
+    _V_SCOPE_MAX_FILES="${VERIFY_SCOPE_MAX_FILES:-}" \
+    _V_SCOPE_MAX_NET="${VERIFY_SCOPE_MAX_NET_LINES:-}" \
     python3 - <<'PYEOF'
 import json, os, hashlib
 
@@ -1432,6 +1603,33 @@ if _ledger_sha:
         "hash_ok": (os.environ.get("_V_LEDGER_HASHOK") == "true"),
     }
 
+# Code-scope / locality record (rank 10, advisory-first). Additive top-level
+# "scope" object; the verdict here is a LABEL only and never affects the
+# document's authoritative verdict/exit_code. Emitted only when the scope helper
+# ran (env set), so evidence.json stays byte-identical on paths that skip it.
+_scope_verdict = os.environ.get("_V_SCOPE_VERDICT") or ""
+if _scope_verdict:
+    def _to_int(name, default=0):
+        v = os.environ.get(name) or ""
+        try:
+            return int(v)
+        except (TypeError, ValueError):
+            return default
+    _thresholds = {
+        "soft_files": _to_int("_V_SCOPE_SOFT_FILES"),
+        "soft_net_lines": _to_int("_V_SCOPE_SOFT_NET"),
+        # Hard caps are opt-in; None when not explicitly set.
+        "max_files": (_to_int("_V_SCOPE_MAX_FILES") if (os.environ.get("_V_SCOPE_MAX_FILES") or "") != "" else None),
+        "max_net_lines": (_to_int("_V_SCOPE_MAX_NET") if (os.environ.get("_V_SCOPE_MAX_NET") or "") != "" else None),
+    }
+    doc["scope"] = {
+        "files_changed": _to_int("_V_SCOPE_FILES"),
+        "net_lines": _to_int("_V_SCOPE_NET"),
+        "verdict": _scope_verdict,
+        "advisory": True,
+        "thresholds": _thresholds,
+    }
+
 os.makedirs(out_dir, exist_ok=True)
 ev_path = os.path.join(out_dir, "evidence.json")
 with open(ev_path, "w") as f:
@@ -2069,6 +2267,11 @@ verify_main() {
 
     verify_diff_base "$base_ref"
 
+    # Code-scope / locality record (rank 10, advisory-first). Reads the diff
+    # stats verify_diff_base just computed; never emits a gate row or feeds the
+    # verdict, so it can never block or change the exit code.
+    verify_scope_record
+
     # Short-circuit on an empty or unresolvable change set. A verifier verifies
     # a CHANGE; with nothing to verify there is no basis for a VERIFIED verdict.
     # Recording the gates as skipped (rather than running them against the whole

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.114.0"
+__version__ = "7.115.0"
 
 # Expose the control app for easy import
 try:

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.114.0
+**Version:** v7.115.0
 
 ---
 

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var q8=Object.defineProperty;var J8=($)=>$;function V8($,Q){this[$]=J8.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)q8($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:V8.bind(Q,Z)})};var P=($,Q)=>()=>($&&(Q=$($=0)),Q);var J$=import.meta.require;var m1={};b(m1,{lokiDir:()=>j,homeLokiDir:()=>T$,findRepoRootForVersion:()=>$1,REPO_ROOT:()=>h});import{resolve as t,dirname as e$}from"path";import{fileURLToPath as W8}from"url";import{existsSync as N$}from"fs";import{homedir as H8}from"os";function G8(){let $=v1;for(let Q=0;Q<6;Q++){if(N$(t($,"VERSION"))&&N$(t($,"autonomy/run.sh")))return $;let Z=e$($);if(Z===$)break;$=Z}return t(v1,"..","..","..")}function $1($){let Q=$;for(let Z=0;Z<6;Z++){if(N$(t(Q,"VERSION"))&&N$(t(Q,"autonomy/run.sh")))return Q;let z=e$(Q);if(z===Q)break;Q=z}return t($,"..","..","..")}function j(){return process.env.LOKI_DIR??t(process.cwd(),".loki")}function T$(){return t(H8(),".loki")}var v1,h;var C=P(()=>{v1=e$(W8(import.meta.url));h=G8()});import{readFileSync as U8}from"fs";import{resolve as Y8,dirname as B8}from"path";import{fileURLToPath as M8}from"url";function S$(){if(Q$!==null)return Q$;let $="7.114.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=B8(M8(import.meta.url)),Z=$1(Q);Q$=U8(Y8(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var Q1=P(()=>{C()});var p1={};b(p1,{runOrThrow:()=>S8,run:()=>R,readStreamCapped:()=>c1,commandVersion:()=>C8,commandExists:()=>u,ShellError:()=>Z1,MAX_STDOUT_BYTES:()=>u1});async function c1($,Q=u1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:W}=await Z.read();if(K)break;if(!W)continue;if(q+=W.byteLength,q>Q){let V=W.byteLength-(q-Q);X+=z.decode(W.subarray(0,V),{stream:!0});break}X+=z.decode(W,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function R($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,W]=await Promise.all([c1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:W}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function S8($,Q={}){let Z=await R($,Q);if(Z.exitCode!==0)throw new Z1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function u($){let Q=D8($),Z=await R(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function D8($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function C8($,Q="--version"){if(!await u($))return null;let z=await R([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var u1=16777216,Z1;var o=P(()=>{Z1=class Z1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function r($){return b8?"":$}var b8,M,S,_,tZ,L,k,y,J;var p=P(()=>{b8=(process.env.NO_COLOR??"").length>0;M=r("\x1B[0;31m"),S=r("\x1B[0;32m"),_=r("\x1B[1;33m"),tZ=r("\x1B[0;34m"),L=r("\x1B[0;36m"),k=r("\x1B[1m"),y=r("\x1B[2m"),J=r("\x1B[0m")});import{existsSync as l8}from"fs";async function Z$(){if(A$!==void 0)return A$;let $="/opt/homebrew/bin/python3.12";if(l8($))return A$=$,$;let Q=await u("python3.12");if(Q)return A$=Q,Q;let Z=await u("python3");return A$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return R([Z,"-c",$],Q)}var A$;var V$=P(()=>{o()});var V0={};b(V0,{runStatus:()=>U3});import{existsSync as v,readFileSync as H$,readdirSync as $0,statSync as Q0}from"fs";import{resolve as D,basename as z3}from"path";import{homedir as X3}from"os";function Z0($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function z0($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*C$/Q);if(X>C$)X=C$;let q=C$-X,K=S;if(z>=80)K=M;else if(z>=50)K=_;let W="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),V=Z0($),H=Z0(Q);return`  ${k}${Z}${J} ${K}[${W}]${J} ${z}% (${V} / ${H})`}async function q3(){if(await u("jq"))return!0;return process.stdout.write(`${M}Error: jq is required but not installed.${J}
+var q8=Object.defineProperty;var J8=($)=>$;function V8($,Q){this[$]=J8.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)q8($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:V8.bind(Q,Z)})};var P=($,Q)=>()=>($&&(Q=$($=0)),Q);var J$=import.meta.require;var m1={};b(m1,{lokiDir:()=>j,homeLokiDir:()=>T$,findRepoRootForVersion:()=>$1,REPO_ROOT:()=>h});import{resolve as t,dirname as e$}from"path";import{fileURLToPath as W8}from"url";import{existsSync as N$}from"fs";import{homedir as H8}from"os";function G8(){let $=v1;for(let Q=0;Q<6;Q++){if(N$(t($,"VERSION"))&&N$(t($,"autonomy/run.sh")))return $;let Z=e$($);if(Z===$)break;$=Z}return t(v1,"..","..","..")}function $1($){let Q=$;for(let Z=0;Z<6;Z++){if(N$(t(Q,"VERSION"))&&N$(t(Q,"autonomy/run.sh")))return Q;let z=e$(Q);if(z===Q)break;Q=z}return t($,"..","..","..")}function j(){return process.env.LOKI_DIR??t(process.cwd(),".loki")}function T$(){return t(H8(),".loki")}var v1,h;var C=P(()=>{v1=e$(W8(import.meta.url));h=G8()});import{readFileSync as U8}from"fs";import{resolve as Y8,dirname as B8}from"path";import{fileURLToPath as M8}from"url";function S$(){if(Q$!==null)return Q$;let $="7.115.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=B8(M8(import.meta.url)),Z=$1(Q);Q$=U8(Y8(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var Q1=P(()=>{C()});var p1={};b(p1,{runOrThrow:()=>S8,run:()=>R,readStreamCapped:()=>c1,commandVersion:()=>C8,commandExists:()=>u,ShellError:()=>Z1,MAX_STDOUT_BYTES:()=>u1});async function c1($,Q=u1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:W}=await Z.read();if(K)break;if(!W)continue;if(q+=W.byteLength,q>Q){let V=W.byteLength-(q-Q);X+=z.decode(W.subarray(0,V),{stream:!0});break}X+=z.decode(W,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function R($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,W]=await Promise.all([c1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:W}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function S8($,Q={}){let Z=await R($,Q);if(Z.exitCode!==0)throw new Z1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function u($){let Q=D8($),Z=await R(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function D8($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function C8($,Q="--version"){if(!await u($))return null;let z=await R([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var u1=16777216,Z1;var o=P(()=>{Z1=class Z1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function r($){return b8?"":$}var b8,M,S,_,tZ,L,k,y,J;var p=P(()=>{b8=(process.env.NO_COLOR??"").length>0;M=r("\x1B[0;31m"),S=r("\x1B[0;32m"),_=r("\x1B[1;33m"),tZ=r("\x1B[0;34m"),L=r("\x1B[0;36m"),k=r("\x1B[1m"),y=r("\x1B[2m"),J=r("\x1B[0m")});import{existsSync as l8}from"fs";async function Z$(){if(A$!==void 0)return A$;let $="/opt/homebrew/bin/python3.12";if(l8($))return A$=$,$;let Q=await u("python3.12");if(Q)return A$=Q,Q;let Z=await u("python3");return A$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return R([Z,"-c",$],Q)}var A$;var V$=P(()=>{o()});var V0={};b(V0,{runStatus:()=>U3});import{existsSync as v,readFileSync as H$,readdirSync as $0,statSync as Q0}from"fs";import{resolve as D,basename as z3}from"path";import{homedir as X3}from"os";function Z0($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function z0($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*C$/Q);if(X>C$)X=C$;let q=C$-X,K=S;if(z>=80)K=M;else if(z>=50)K=_;let W="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),V=Z0($),H=Z0(Q);return`  ${k}${Z}${J} ${K}[${W}]${J} ${z}% (${V} / ${H})`}async function q3(){if(await u("jq"))return!0;return process.stdout.write(`${M}Error: jq is required but not installed.${J}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -814,4 +814,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write(K8),2}}e1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var SZ=await NZ(Bun.argv.slice(2));process.exit(SZ);
 
-//# debugId=0888AC629271567B64756E2164756E21
+//# debugId=7679240CF905E39B64756E2164756E21

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '7.114.0'
+__version__ = '7.115.0'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.114.0",
+  "version": "7.115.0",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "7.114.0",
+  "version": "7.115.0",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",