loki-mode 7.93.0 → 7.94.0

package/autonomy/lib/done-recognition.sh

@@ -0,0 +1,823 @@
+#!/usr/bin/env bash
+# done-recognition.sh -- model-verified "already done?" gate for no-PRD reuse runs.
+#
+# Problem: a `loki start` with NO PRD over a project Loki already built and
+# completed reverse-engineers (reuses) the prior generated PRD and then rebuilds
+# a full task queue and re-runs the RARV loop, re-doing finished work. The reuse
+# path never asks "is this reused PRD already satisfied by the current codebase?"
+#
+# This module inserts ONE localized gate in run_autonomous() between load_state
+# and the queue/loop. On a no-PRD reuse run it re-verifies ground truth with the
+# model (re-runs tests via the existing completion-test-evidence path, inspects
+# code per requirement) and routes to one of three outcomes:
+#   - done        -> refresh the verified-completion record + finish through the
+#                    normal completion path (no wasted iterations, no queue).
+#   - incomplete  -> write a satisfied-requirements manifest so populate_prd_queue
+#                    builds ONLY the unsatisfied requirements.
+#   - inconclusive-> do nothing; fall through to the normal full build (safe
+#                    default). NEVER declare done on inconclusive.
+#
+# TRUST MOAT: a model `done` is DOWNGRADED to build if fresh tests are red or any
+# requirement is unmet/uncertain. The positive verdict is always the model's,
+# grounded in re-run reality, never asserted from a stale artifact. The `update`
+# action (PRD stale by definition) may NEVER fast-stop as done.
+#
+# MODEL INTELLIGENCE, NEVER HARDCODED: the only deterministic short-circuit is
+# NEGATIVE (cheap signals that route to BUILD). There is no deterministic
+# "checklist all-verified -> stop" shortcut.
+#
+# Rollout: DEFAULT-ON. LOKI_DONE_RECOGNITION=0 disables the gate (legacy
+# reuse-then-build behavior). Trust-safe because inconclusive always falls
+# through to build.
+#
+# Indirection (for testability): the actual model call goes through
+#   _loki_done_recog_invoke <prompt>   (echoes the raw model response)
+# Tests stub this function to return canned JSON without a real model. This is
+# the single injection seam, mirroring autonomy/lib/prd-enrich.sh.
+#
+# No emojis. No em dashes. bash 3.2 safe. Honors `set -uo pipefail`.
+
+# Bound the single model call so a huge PRD or test log cannot run away.
+: "${LOKI_DONE_RECOG_TIMEOUT:=180}"           # seconds for the single model call
+: "${LOKI_DONE_RECOG_MAX_PRD_CHARS:=16000}"   # cap PRD context length
+: "${LOKI_DONE_RECOG_MAX_TEST_CHARS:=4000}"   # cap test-results context length
+
+# The single model-call primitive. Kept as its own function so:
+#   1. it is the ONE place that touches the provider, and
+#   2. tests can override it to return canned JSON.
+# Mirrors _loki_prd_enrich_invoke (autonomy/lib/prd-enrich.sh:43) verbatim in
+# shape. Calls `claude -p` directly (not provider_invoke) because `timeout`
+# needs a real command, not a shell function.
+_loki_done_recog_invoke() {
+    local prompt="$1"
+    command -v claude >/dev/null 2>&1 || return 1
+    local rc=0
+    local out=""
+    if command -v timeout >/dev/null 2>&1; then
+        out=$(CAVEMAN_DEFAULT_MODE=off timeout "${LOKI_DONE_RECOG_TIMEOUT}" \
+                  claude --dangerously-skip-permissions -p "$prompt" 2>/dev/null) || rc=$?
+    else
+        out=$(CAVEMAN_DEFAULT_MODE=off \
+                  claude --dangerously-skip-permissions -p "$prompt" 2>/dev/null) || rc=$?
+    fi
+    [ "$rc" -ne 0 ] && return 1
+    [ -z "$out" ] && return 1
+    printf '%s' "$out"
+    return 0
+}
+
+# Decide whether model verification can be attempted. Returns 0 (ok) only when
+# the active provider is claude and not degraded. Mirrors
+# _loki_prd_enrich_provider_ok (autonomy/lib/prd-enrich.sh:65).
+_loki_done_recog_provider_ok() {
+    [ "${LOKI_PROVIDER:-claude}" = "claude" ] || return 1
+    [ "${PROVIDER_DEGRADED:-false}" != "true" ] || return 1
+    command -v claude >/dev/null 2>&1 || return 1
+    return 0
+}
+
+# Compute the PRD identity hash. MUST be byte-identical here (writer) and in
+# populate_prd_queue's manifest read-point (reader) or the guard always
+# mismatches and silently falls back to a full build. Pinned to the same file
+# and the same hashing path on both sides via this one helper.
+_loki_done_recog_prd_sha() {
+    local prd_file="${1:-}"
+    [ -n "$prd_file" ] && [ -f "$prd_file" ] || { printf ''; return 0; }
+    if command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$prd_file" 2>/dev/null | awk '{print $1}'
+    elif command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$prd_file" 2>/dev/null | awk '{print $1}'
+    else
+        # Last-resort: a python hash, still deterministic over the same bytes.
+        LOKI_DR_PRD="$prd_file" python3 -c "
+import hashlib, os
+p = os.environ.get('LOKI_DR_PRD','')
+try:
+    with open(p,'rb') as f:
+        print(hashlib.sha256(f.read()).hexdigest())
+except Exception:
+    print('')
+" 2>/dev/null
+    fi
+}
+
+# The gate. Called once, run-scoped, from run_autonomous() AFTER load_state and
+# BEFORE the delegate-branch/start-sha block and populate_prd_queue.
+#
+# Arguments:
+#   $1 = prd_path (the reused generated PRD, e.g. .loki/generated-prd.md)
+#
+# Behavior by outcome:
+#   done        -> writes refreshed completion record, runs council-parity
+#                  finalization subset (all type-guarded), returns 0 so the
+#                  caller's `return 0` skips queue-build + loop and main()'s
+#                  terminal block finalizes the run.
+#   incomplete  -> writes .loki/state/satisfied-requirements.json, returns 1 so
+#                  the caller falls through to a (now incremental) build.
+#   inconclusive/fast-path/disabled -> returns 1 (fall through to build).
+#
+# Return contract:
+#   0 = DONE (caller must short-circuit: `return 0` from run_autonomous)
+#   1 = BUILD (caller falls through to the normal queue/loop)
+reuse_done_recognition_gate() {
+    local prd_path="${1:-}"
+    local action="${GENERATED_PRD_ACTION:-}"
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+
+    # --- Opt-out (rollout escape hatch). Default-on. -------------------------
+    if [ "${LOKI_DONE_RECOGNITION:-1}" = "0" ]; then
+        return 1
+    fi
+
+    # Must have a usable reused PRD to judge against.
+    [ -n "$prd_path" ] && [ -f "$prd_path" ] || return 1
+
+    # --- Negative fast-path A: no completion footprint at all ----------------
+    # The project was never completed by a prior run; there is nothing plausibly
+    # done. Never pay for a model call. (Cheapest, most common miss-avoidance.)
+    if [ ! -f "$loki_dir/signals/COMPLETION_REQUESTED" ] \
+       && [ ! -f "$loki_dir/state/completion.json" ] \
+       && [ ! -f "$loki_dir/checklist/checklist.json" ]; then
+        log_info "Done-recognition: no prior completion footprint; proceeding to build."
+        return 1
+    fi
+
+    # --- Negative fast-path B: provider cannot model-verify -------------------
+    # Cannot model-verify -> inconclusive -> build (never assert done offline).
+    if ! _loki_done_recog_provider_ok; then
+        log_info "Done-recognition: provider cannot verify (non-claude/degraded/no binary); proceeding to build."
+        return 1
+    fi
+
+    log_step "Done-recognition: checking whether the existing code already satisfies the reused spec..."
+
+    # --- Ground-truth re-verification: re-run tests NOW ----------------------
+    # Reuse the SAME evidence axis the completion council/evidence gate reads, so
+    # the gate cannot reach a verdict that contradicts the council. Swallow rc
+    # (red tests are data, not a crash). When unavailable the file is simply
+    # absent and the test axis is honestly inconclusive.
+    if type ensure_completion_test_evidence >/dev/null 2>&1; then
+        ensure_completion_test_evidence || true
+    fi
+    local _test_results="$loki_dir/quality/test-results.json"
+
+    # --- Build the model prompt payload (python: bounded, defensive) ---------
+    local prompt
+    prompt=$(LOKI_DR_PRD="$prd_path" \
+             LOKI_DR_TESTS="$_test_results" \
+             LOKI_DR_COMPLETION="$loki_dir/state/completion.json" \
+             LOKI_DR_EVIDENCE="$loki_dir/completion-evidence.md" \
+             LOKI_DR_CHECKLIST="$loki_dir/checklist/checklist.json" \
+             LOKI_DR_MAX_PRD="${LOKI_DONE_RECOG_MAX_PRD_CHARS}" \
+             LOKI_DR_MAX_TEST="${LOKI_DONE_RECOG_MAX_TEST_CHARS}" \
+             python3 << 'DR_PROMPT_EOF'
+import json, os, sys
+
+def read_capped(path, cap):
+    try:
+        with open(path, "r", errors="replace") as f:
+            return f.read()[:cap]
+    except Exception:
+        return ""
+
+prd = read_capped(os.environ.get("LOKI_DR_PRD", ""),
+                  int(os.environ.get("LOKI_DR_MAX_PRD", "16000") or "16000"))
+if not prd.strip():
+    sys.exit(0)
+
+tests = read_capped(os.environ.get("LOKI_DR_TESTS", ""),
+                    int(os.environ.get("LOKI_DR_MAX_TEST", "4000") or "4000"))
+completion = read_capped(os.environ.get("LOKI_DR_COMPLETION", ""), 2000)
+evidence = read_capped(os.environ.get("LOKI_DR_EVIDENCE", ""), 2000)
+checklist = read_capped(os.environ.get("LOKI_DR_CHECKLIST", ""), 2000)
+
+prompt = """You are deciding whether a codebase ALREADY satisfies its spec, so a
+build system can skip rebuilding work that is already done. Be rigorous and
+conservative: a wrong "done" wastes the user's trust, a wrong "incomplete" only
+costs a little rebuild. When unsure, say uncertain.
+
+For EACH requirement in the PRD below:
+  - Inspect the ACTUAL code in this repository (read the files) and the fresh
+    test results, and decide whether the requirement is met NOW.
+  - Treat all prior Loki artifacts (PRIOR CLAIMS section) as UNVERIFIED claims.
+    Do NOT trust them; verify against the code and the fresh test results.
+
+Then return ONLY a single JSON object (no prose, no markdown fences):
+{
+  "verdict": "done" | "incomplete" | "inconclusive",
+  "summary": "<one plain sentence for the user>",
+  "tests": { "passed": <int>, "total": <int>, "green": true|false },
+  "requirements": [
+    { "id": "<stable id or title slug>",
+      "title": "<requirement title, matching the PRD feature heading>",
+      "status": "met" | "unmet" | "uncertain",
+      "evidence": "<file:line or test name proving it>" }
+  ]
+}
+
+Verdict rules:
+  - "done" ONLY when ALL requirements are "met" AND the fresh tests are green
+    (or there is no test runner and you can cite concrete code evidence for
+    every requirement).
+  - "incomplete" when one or more requirements are "unmet".
+  - "inconclusive" when you cannot establish ground truth.
+No emojis. No em dashes.
+
+=== PRD (the requirements to verify) ===
+%s
+
+=== FRESH TEST RESULTS (re-run now; authoritative for the test axis) ===
+%s
+
+=== PRIOR CLAIMS (possibly stale; verify, do not trust) ===
+completion.json:
+%s
+completion-evidence.md:
+%s
+checklist.json:
+%s
+""" % (prd, tests or "(no test results captured)",
+       completion or "(none)", evidence or "(none)", checklist or "(none)")
+
+sys.stdout.write(prompt)
+DR_PROMPT_EOF
+)
+
+    # Empty payload (unreadable/empty PRD) -> inconclusive -> build.
+    if [ -z "$prompt" ]; then
+        log_info "Done-recognition: could not build a verification payload; proceeding to build."
+        return 1
+    fi
+
+    # --- The single model call (the mockable seam) ---------------------------
+    local response
+    response=$(_loki_done_recog_invoke "$prompt") || {
+        log_info "Done-recognition: model verification unavailable (timeout/error); proceeding to build."
+        return 1
+    }
+    if [ -z "$response" ]; then
+        log_info "Done-recognition: empty verification response; proceeding to build."
+        return 1
+    fi
+
+    # --- Parse + DEFENSIVELY re-derive the verdict (never trust top-line) ----
+    # The python parser slices first '{' to last '}' (tolerate prose/fences),
+    # re-derives the verdict from the per-requirement statuses + fresh test
+    # axis, and emits a compact result the bash side routes on. `update` action
+    # may NEVER yield a fast-stop done: it is forced to "incomplete" when the
+    # model said done (downgraded to inconclusive if no requirement is met).
+    local parsed
+    parsed=$(LOKI_DR_RESP="$response" \
+             LOKI_DR_TESTS="$_test_results" \
+             LOKI_DR_ACTION="$action" \
+             LOKI_DR_PRD="$prd_path" \
+             python3 << 'DR_PARSE_EOF'
+import json, os, re, sys
+
+resp = os.environ.get("LOKI_DR_RESP", "")
+action = os.environ.get("LOKI_DR_ACTION", "")
+tests_path = os.environ.get("LOKI_DR_TESTS", "")
+prd_path = os.environ.get("LOKI_DR_PRD", "")
+
+def parse_object(text):
+    try:
+        v = json.loads(text)
+        if isinstance(v, dict):
+            return v
+    except Exception:
+        pass
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        return None
+    try:
+        v = json.loads(text[start:end + 1])
+        return v if isinstance(v, dict) else None
+    except Exception:
+        return None
+
+obj = parse_object(resp)
+if obj is None:
+    print(json.dumps({"verdict": "inconclusive", "reason": "unparsable verdict",
+                      "summary": "", "satisfied": []}))
+    sys.exit(0)
+
+reqs = obj.get("requirements")
+if not isinstance(reqs, list):
+    reqs = []
+
+statuses = []
+satisfied = []
+for r in reqs:
+    if not isinstance(r, dict):
+        continue
+    st = str(r.get("status", "")).strip().lower()
+    title = (r.get("title") or "").strip()
+    statuses.append(st)
+    if st == "met" and title:
+        satisfied.append(title)
+
+# Fresh-test axis: authoritative. Read the persisted test-results.json and
+# decide green/red/unknown INDEPENDENTLY of the model's self-report.
+def tests_axis(path):
+    try:
+        with open(path, "r") as f:
+            d = json.load(f)
+    except Exception:
+        return "unknown"  # no runner / no file -> not authoritative
+    if not isinstance(d, dict):
+        return "unknown"
+    # PRODUCTION shapes first (enforce_test_coverage in run.sh writes these):
+    #   real runner green : {"pass": true,  "status": "verified", "exit_code": 0}
+    #   real runner red   : {"pass": false, "status": "failed",   "exit_code": 1}
+    #   no runner         : {"pass": "inconclusive", "status": "not_run", "runner": "none"}
+    status = str(d.get("status", "")).strip().lower()
+    if status in ("not_run", "skipped", "none", "inconclusive"):
+        return "unknown"  # no authoritative run happened
+    # exit_code is the most authoritative red signal when present and numeric.
+    ec = d.get("exit_code")
+    if isinstance(ec, bool):
+        ec = None  # guard: bool is an int subclass; do not treat true/false as 0/1
+    if isinstance(ec, int):
+        if ec != 0:
+            return "red"
+        # exit 0 alone is green only if nothing else contradicts it (checked below).
+    p = d.get("pass")
+    if p is True:
+        # A clean pass:true with no contradicting red signal is authoritative green.
+        if d.get("failed") in (None, 0) and (ec in (None, 0)):
+            return "green"
+    if p is False:
+        return "red"
+    # Legacy / generic shapes.
+    failed = d.get("failed")
+    if isinstance(failed, int):
+        return "green" if failed == 0 else "red"
+    if status in ("pass", "passed", "green", "ok", "success", "verified"):
+        return "green"
+    if status in ("fail", "failed", "red", "error"):
+        return "red"
+    passed = d.get("passed")
+    total = d.get("total")
+    if isinstance(passed, int) and isinstance(total, int) and total > 0:
+        return "green" if passed >= total else "red"
+    # exit_code 0 with no other signal: treat as green (a runner ran and succeeded).
+    if isinstance(ec, int) and ec == 0:
+        return "green"
+    return "unknown"
+
+axis = tests_axis(tests_path)
+
+# Requirement COVERAGE guard (deterministic, NEGATIVE-only: it can only route
+# toward build, never toward done). The model returning "all met" over a SUBSET
+# of the PRD is a fake-green: it silently declares unbuilt features satisfied.
+# So we independently parse the PRD's feature/requirement titles and require the
+# model to have COVERED every one. Any PRD title the model did not return a
+# status for -> coverage gap -> done is not trustworthy.
+def _norm_title(t):
+    t = (t or "").strip().lower()
+    # Mirror the populate_prd_queue normalization: drop a leading
+    # "feature:"/"requirement:" label and surrounding markdown/heading marks.
+    t = re.sub(r"^\s*(?:feature|requirement)\s*[:\-]\s*", "", t)
+    t = re.sub(r"^[#\s>*\-]+", "", t)
+    t = re.sub(r"\s+", " ", t).strip()
+    return t
+
+def prd_feature_titles(path):
+    """Best-effort PRD feature/requirement titles. Honest: returns None when we
+    cannot reliably enumerate (so the guard does NOT fire on an unparseable PRD
+    and wrongly block a real done -- it only fires when we DO know the set)."""
+    if not path or not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", errors="replace") as f:
+            raw = f.read()
+    except Exception:
+        return None
+    if not raw.strip():
+        return None
+    titles = []
+    # JSON PRD: collect "title"/"name"/"feature"/"requirement" values.
+    try:
+        d = json.loads(raw)
+        def walk(o):
+            if isinstance(o, dict):
+                for k, v in o.items():
+                    if k in ("title", "name", "feature", "requirement") and isinstance(v, str) and v.strip():
+                        titles.append(v)
+                    else:
+                        walk(v)
+            elif isinstance(o, list):
+                for it in o:
+                    walk(it)
+        walk(d)
+        if titles:
+            return [_norm_title(t) for t in titles if _norm_title(t)]
+    except Exception:
+        pass
+    # Markdown PRD. Loki's OWN generated PRDs (the canonical reuse target, written
+    # by the codebase-analysis prompt) do NOT use "## Feature:" markers -- they use
+    # sections like "## Existing Behavior and Requirements" with bullet items. So
+    # we must enumerate from multiple shapes, not just an explicit Feature: label:
+    #   - explicit "Feature:"/"Requirement:" lines (any depth)
+    #   - bullet/numbered requirement items under a requirements-like section
+    #   - sub-section headings (### ...) that name a discrete capability
+    # A bare top-level document title (the single "# Title" line) is excluded.
+    REQ_SECTION = re.compile(r"requirement|feature|behavior|capabilit|user stor|acceptance", re.I)
+    NON_FEATURE = ("overview", "summary", "prd", "spec", "requirements", "features",
+                   "scope", "goals", "detected stack", "stack", "non-goals",
+                   "out of scope", "context", "background", "existing behavior and requirements")
+    in_req_section = False
+    for line in raw.splitlines():
+        s = line.strip()
+        if not s:
+            continue
+        # Explicit label anywhere.
+        m = re.match(r"^(?:[#>*\-\d.\s]+)?(?:feature|requirement)\s*[:\-]\s+(.+)$", s, re.I)
+        if m:
+            n = _norm_title(m.group(1))
+            if n and n not in NON_FEATURE:
+                titles.append(n)
+            continue
+        # Section heading: track whether we are inside a requirements-like section.
+        hm = re.match(r"^#{1,6}\s+(.+)$", s)
+        if hm:
+            head = _norm_title(hm.group(1))
+            in_req_section = bool(REQ_SECTION.search(head))
+            # A discrete sub-section heading (###+) that is not a known non-feature
+            # label is itself a feature title.
+            if re.match(r"^#{3,6}\s+", s) and head and head not in NON_FEATURE:
+                titles.append(head)
+            continue
+        # Bullet / numbered item inside a requirements-like section is a requirement.
+        if in_req_section:
+            bm = re.match(r"^(?:[-*+]|\d+[.)])\s+(.+)$", s)
+            if bm:
+                n = _norm_title(bm.group(1))
+                # Keep it short-ish (a requirement line, not a paragraph) and real.
+                if n and n not in NON_FEATURE and len(n) <= 200:
+                    titles.append(n)
+    # Dedup, preserve order.
+    seen = set(); uniq = []
+    for t in titles:
+        if t not in seen:
+            seen.add(t); uniq.append(t)
+    return uniq if uniq else None
+
+all_met = len(statuses) > 0 and all(s == "met" for s in statuses)
+any_unmet = any(s == "unmet" for s in statuses)
+any_met = any(s == "met" for s in statuses)
+
+# Coverage check: did the model address every PRD feature? If the PRD set is
+# known and the model omitted any of it, the "all met" is over a subset -> not
+# trustworthy as done.
+_prd_titles = prd_feature_titles(prd_path)
+_covered = set(_norm_title(t) for t in (
+    (r.get("title") or "") for r in reqs if isinstance(r, dict)
+) if _norm_title(t))
+# coverage_gap is True when we KNOW the model under-enumerated the spec.
+# coverage_unknown is True when we could NOT enumerate the PRD at all -- in which
+# case we CANNOT trust a done (a wrong done burns trust; a wrong incomplete only
+# costs a rebuild). Per the NEGATIVE-only-fast-path rule, an inability to verify
+# coverage must block done, never enable it.
+coverage_gap = False
+coverage_unknown = _prd_titles is None
+if _prd_titles is not None:
+    _missing = [t for t in set(_prd_titles) if t not in _covered]
+    coverage_gap = len(_missing) > 0
+
+# The model's own top-line verdict. It is NECESSARY-but-not-sufficient for done:
+# the defensive re-derivation can only ever DOWNGRADE from it, never upgrade. If
+# the model itself did not say done (inconclusive/incomplete), we must not fast-
+# stop even when the per-requirement breakdown looks all-met -- that would
+# override the model's explicit negative judgment (critical-check-1: inconclusive
+# falls through to build; critical-check-2: the positive decision is the model's,
+# never a deterministic all-met=>done shortcut).
+obj_verdict = str(obj.get("verdict", "")).strip().lower()
+model_says_done = obj_verdict == "done"
+
+# Defensive re-derivation: the model must say done AND every objective guard must
+# pass. done requires: model top-line done AND all requirements met AND tests not
+# red AND no coverage gap/unknown. Any guard failing downgrades (never upgrades).
+if model_says_done and all_met and axis != "red" and not coverage_gap and not coverage_unknown:
+    verdict = "done"
+elif model_says_done and coverage_unknown and all_met and axis != "red":
+    # Even with a model 'done', if we cannot enumerate the PRD to confirm full
+    # coverage, route to inconclusive -> build (no fake-green over an unverifiable
+    # spec). Handled by the coverage_unknown branch below; fall through.
+    verdict = "inconclusive"
+elif all_met and axis != "red" and not coverage_gap and not coverage_unknown and not model_says_done:
+    # Per-requirement breakdown looks complete but the MODEL did not declare done
+    # (it said inconclusive/incomplete). Respect the model: do not fast-stop.
+    verdict = "inconclusive"
+elif coverage_unknown and all_met and axis != "red":
+    # We could not enumerate the PRD to confirm the model covered all of it. A
+    # done over an unverifiable spec is a fake-green risk (the model may have
+    # addressed a subset). Route to inconclusive -> build, never a fast-stop.
+    verdict = "inconclusive"
+elif coverage_gap and all_met and axis != "red":
+    # Model reported all-met but did not cover every PRD feature -> it declared a
+    # SUBSET done. Never a fast-stop on partial coverage (no fake-green). The met
+    # subset can still seed an incremental build of the omitted features.
+    verdict = "incomplete"
+elif any_unmet or (any_met and not all_met):
+    verdict = "incomplete"
+elif all_met and axis == "red":
+    # Model claimed everything met but fresh tests are red -> downgrade.
+    verdict = "incomplete"
+else:
+    verdict = "inconclusive"
+
+# The `update` action's PRD is stale by definition; a fast-stop done is a
+# false-stop risk. Force done -> incomplete (incremental) when any requirement
+# is met, else inconclusive. NEVER a fast-stop on update.
+if action == "update" and verdict == "done":
+    verdict = "incomplete" if any_met else "inconclusive"
+
+reason = ""
+if verdict == "inconclusive":
+    if not statuses:
+        reason = "no per-requirement evidence returned"
+    elif axis == "red":
+        reason = "fresh tests are red"
+    else:
+        reason = "could not establish ground truth"
+
+# On incomplete we only trust the met set when the tests are not red; a red
+# suite means even "met" claims are unverified, so the manifest stays empty
+# (rebuild everything) rather than risk skipping broken work.
+if verdict == "incomplete" and axis == "red":
+    satisfied = []
+
+print(json.dumps({
+    "verdict": verdict,
+    "summary": (obj.get("summary") or "").strip(),
+    "reason": reason,
+    "tests_axis": axis,
+    "met_count": len([s for s in statuses if s == "met"]),
+    "total_count": len(statuses),
+    "prd_feature_count": (len(set(_prd_titles)) if _prd_titles is not None else None),
+    "coverage_gap": coverage_gap,
+    "satisfied": satisfied,
+}))
+DR_PARSE_EOF
+)
+
+    if [ -z "$parsed" ]; then
+        log_info "Done-recognition: verdict parse produced no result; proceeding to build."
+        return 1
+    fi
+
+    local verdict
+    verdict=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('verdict',''))" 2>/dev/null)
+
+    case "$verdict" in
+        done)
+            _loki_done_recog_finish "$prd_path" "$parsed"
+            return 0
+            ;;
+        incomplete)
+            _loki_done_recog_write_manifest "$prd_path" "$parsed"
+            return 1
+            ;;
+        *)
+            local _reason
+            _reason=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('reason','') or 'unverifiable')" 2>/dev/null)
+            log_info "Done-recognition: could not confirm the existing code already satisfies the reused spec (${_reason}). Proceeding to build to be safe."
+            return 1
+            ;;
+    esac
+}
+
+# done path: refresh the verified-completion record (gate-owned, so it is
+# deterministic even when sourced standalone in tests) and run the council-parity
+# finalization subset (all type-guarded best-effort). The caller's `return 0`
+# then skips the queue/loop, and main()'s terminal block finalizes the run.
+_loki_done_recog_finish() {
+    local prd_path="$1"
+    local parsed="$2"
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+
+    # The gate runs EARLY in run_autonomous, before the run normally mints these
+    # run-scoped ids/baselines (run.sh sets them just after this call site). The
+    # council-parity finalizers below (and what they transitively call) expect
+    # them. run.sh is under `set -u`, so mint/guard them here if-absent so a real
+    # done verdict never references an unbound var. Idempotent: := only sets when
+    # unset, so this never clobbers a value the run already minted. The if-absent
+    # trust-run-id mint is exactly the ordering fix the plan prescribes (no
+    # hoisting of run.sh's existing block, keeping the change localized).
+    if [ -z "${LOKI_TRUST_RUN_ID:-}" ] && type _loki_trust_run_id >/dev/null 2>&1; then
+        LOKI_TRUST_RUN_ID="$(_loki_trust_run_id --new 2>/dev/null || echo "")"
+        export LOKI_TRUST_RUN_ID
+    fi
+    : "${LOKI_TRUST_RUN_ID:=}"
+    : "${_LOKI_RUN_START_SHA:=}"
+    : "${_LOKI_RUN_START_EPOCH:=$(date +%s 2>/dev/null || echo 0)}"
+    export LOKI_TRUST_RUN_ID _LOKI_RUN_START_SHA _LOKI_RUN_START_EPOCH
+
+    mkdir -p "$loki_dir/state" 2>/dev/null || true
+
+    local summary met total axis
+    summary=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('summary','') or 'Project already satisfies its spec.')" 2>/dev/null)
+    met=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('met_count',0))" 2>/dev/null)
+    total=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('total_count',0))" 2>/dev/null)
+    axis=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('tests_axis','unknown'))" 2>/dev/null)
+    [ -n "$met" ] || met=0
+    [ -n "$total" ] || total=0
+    [ -n "$axis" ] || axis="unknown"
+    # HONESTY: the receipt must only claim test-backing the gate actually computed.
+    # A green axis means fresh tests ran AND passed now; otherwise the basis is
+    # code inspection alone (no runner / inconclusive) -- never overclaim.
+    local verify_basis
+    if [ "$axis" = "green" ]; then
+        verify_basis="re-ran the tests now (passed) and code inspection"
+    else
+        verify_basis="code inspection (no passing test run was available to confirm)"
+    fi
+
+    # Refresh the verified-completion record reflecting the NOW re-run results.
+    # Prefer the shared standalone writer (one writer, no divergence). It reads
+    # git/state, not loop locals, so it is safe at this pre-loop site. Wrapped
+    # type-guarded so the standalone test (no run.sh) still works.
+    if type build_completion_summary >/dev/null 2>&1; then
+        build_completion_summary complete || true
+    fi
+
+    # Gate-owned durable artifacts (always written, so the receipt + dashboard
+    # reflect THIS verified-done verdict and tests are deterministic). The
+    # per-requirement evidence is recorded as the completion-evidence body.
+    local ts
+    ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    {
+        echo "# Completion Evidence (reuse done-recognition)"
+        echo ""
+        echo "Generated: $ts"
+        echo ""
+        echo "Verdict: done (basis: ${verify_basis})"
+        echo "Requirements met: ${met}/${total}"
+        echo "Fresh-test axis: ${axis}"
+        echo ""
+        echo "Summary: $summary"
+        echo ""
+        echo "## Per-requirement evidence"
+        echo ""
+        printf '%s' "$parsed" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+for t in d.get('satisfied', []):
+    print('- met: %s' % t)
+" 2>/dev/null || true
+    } > "$loki_dir/completion-evidence.md" 2>/dev/null || true
+
+    # Refresh completion.json INLINE (gate-owned), guaranteeing the durable
+    # machine-readable record exists with this verdict even when sourced
+    # standalone. Atomic write.
+    LOKI_DR_OUT="$loki_dir/state/completion.json" \
+    LOKI_DR_SUMMARY="$summary" \
+    LOKI_DR_MET="$met" \
+    LOKI_DR_TOTAL="$total" \
+    LOKI_DR_TS="$ts" \
+    python3 -c "
+import json, os, tempfile
+out = os.environ['LOKI_DR_OUT']
+def i(v):
+    try: return int(v)
+    except (TypeError, ValueError): return 0
+rec = {
+    'outcome': 'complete',
+    'source': 'reuse-done-recognition',
+    'verdict': 'done',
+    'summary': os.environ.get('LOKI_DR_SUMMARY', ''),
+    'requirements_met': i(os.environ.get('LOKI_DR_MET')),
+    'requirements_total': i(os.environ.get('LOKI_DR_TOTAL')),
+    'verified_at': os.environ.get('LOKI_DR_TS', ''),
+}
+d = os.path.dirname(os.path.abspath(out)) or '.'
+try:
+    os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=d, prefix='.completion-', suffix='.json')
+    with os.fdopen(fd, 'w') as f:
+        json.dump(rec, f, indent=2)
+    os.replace(tmp, out)
+except Exception:
+    pass
+" 2>/dev/null || true
+
+    # COMPLETED marker (gate-owned; idempotent overwrite, precedented by the
+    # council force-approve path at run.sh:17692). main() also writes it.
+    echo "Project already satisfied its spec (reuse done-recognition) at $ts" \
+        > "$loki_dir/COMPLETED" 2>/dev/null || true
+
+    # Council-parity finalization subset (mirrors run.sh:17693-17703). All
+    # type-guarded so the standalone test needs zero stubs; production gets full
+    # parity. main() owns _advance_current_phase COMPLETED + proof + handoff.
+    type council_write_report >/dev/null 2>&1 && council_write_report || true
+    type run_memory_consolidation >/dev/null 2>&1 && run_memory_consolidation || true
+    type on_run_complete >/dev/null 2>&1 && on_run_complete || true
+    type emit_completion_summary >/dev/null 2>&1 && emit_completion_summary complete || true
+    type save_state >/dev/null 2>&1 && save_state "${RETRY_COUNT:-0}" "reuse_already_satisfied" 0 || true
+
+    # User-facing message (enterprise UX). The last line names BOTH escape
+    # hatches so a user who WANTS to extend a done project sees them unmissably.
+    log_header "This project already satisfies its spec. Nothing to build." 2>/dev/null \
+        || log_info "This project already satisfies its spec. Nothing to build."
+    if [ "$axis" = "green" ]; then
+        log_info "Verified ${met}/${total} requirements met and re-ran the tests now (passed). ${summary}"
+    else
+        log_info "Verified ${met}/${total} requirements met by code inspection (no passing test run was available to confirm). ${summary}"
+    fi
+    log_info "To rebuild from scratch run 'loki start --fresh-prd'; to extend it, edit the spec or pass a new/changed PRD."
+}
+
+# incomplete path: write the satisfied-requirements manifest so
+# populate_prd_queue skips already-met features. prd_sha-guarded; keyed on
+# feature TITLE (matched case-insensitively in the builder).
+_loki_done_recog_write_manifest() {
+    local prd_path="$1"
+    local parsed="$2"
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+
+    mkdir -p "$loki_dir/state" 2>/dev/null || true
+
+    local prd_sha
+    prd_sha=$(_loki_done_recog_prd_sha "$prd_path")
+    local ts
+    ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+    LOKI_DR_OUT="$loki_dir/state/satisfied-requirements.json" \
+    LOKI_DR_PARSED="$parsed" \
+    LOKI_DR_SHA="$prd_sha" \
+    LOKI_DR_TS="$ts" \
+    python3 -c "
+import json, os, sys, tempfile
+out = os.environ['LOKI_DR_OUT']
+try:
+    parsed = json.loads(os.environ.get('LOKI_DR_PARSED', '{}'))
+except Exception:
+    parsed = {}
+satisfied = parsed.get('satisfied', [])
+if not isinstance(satisfied, list):
+    satisfied = []
+rec = {
+    'prd_sha': os.environ.get('LOKI_DR_SHA', ''),
+    'generated_at': os.environ.get('LOKI_DR_TS', ''),
+    'satisfied': [s for s in satisfied if isinstance(s, str) and s.strip()],
+    'source': 'reuse-done-recognition',
+}
+d = os.path.dirname(os.path.abspath(out)) or '.'
+try:
+    os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=d, prefix='.satisfied-', suffix='.json')
+    with os.fdopen(fd, 'w') as f:
+        json.dump(rec, f, indent=2)
+    os.replace(tmp, out)
+except Exception:
+    pass
+" 2>/dev/null || true
+
+    # The satisfied-requirements manifest is read by populate_prd_queue's
+    # incremental skip-filter -- but populate_prd_queue early-returns when a stale
+    # .prd-populated marker from the PRIOR (completed) run still exists, never
+    # reaching the filter. Clear that marker (and reset the pending queue) so the
+    # incremental rebuild actually runs and skips the satisfied features. Without
+    # this, the founder-locked "build only the unsatisfied gap" behavior is inert.
+    # Use $loki_dir (TARGET_DIR-rooted) for the queue paths too, matching the
+    # manifest path above. run_autonomous runs with cwd==TARGET_DIR so the prior
+    # relative form resolved identically, but a single rooted convention avoids a
+    # latent cwd footgun.
+    rm -f "$loki_dir/queue/.prd-populated" 2>/dev/null || true
+    if [ -f "$loki_dir/queue/pending.json" ]; then
+        # Drop prior PRD-sourced tasks so the incremental pass is the source of
+        # truth; non-PRD tasks (if any) are preserved.
+        LOKI_DR_PENDING="$loki_dir/queue/pending.json" python3 - <<'RESET_EOF' 2>/dev/null || true
+import json, os, tempfile
+p = os.environ.get("LOKI_DR_PENDING", ".loki/queue/pending.json")
+try:
+    with open(p) as f:
+        data = json.load(f)
+except Exception:
+    raise SystemExit(0)
+tasks = data.get("tasks", data) if isinstance(data, dict) else data
+if isinstance(tasks, list):
+    kept = [t for t in tasks if not (isinstance(t, dict) and str(t.get("id", "")).startswith("prd-"))]
+    if isinstance(data, dict):
+        data["tasks"] = kept
+    else:
+        data = kept
+    d = os.path.dirname(os.path.abspath(p)) or "."
+    fd, tmp = tempfile.mkstemp(dir=d, prefix=".pending-", suffix=".json")
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, p)
+RESET_EOF
+    fi
+
+    local met total
+    met=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('met_count',0))" 2>/dev/null)
+    total=$(printf '%s' "$parsed" | python3 -c "import json,sys;print(json.load(sys.stdin).get('total_count',0))" 2>/dev/null)
+    local unmet=$(( ${total:-0} - ${met:-0} ))
+    log_info "Done-recognition: ${met:-0} of ${total:-0} requirements already satisfied; building only the ${unmet} unmet. Pass --fresh-prd to rebuild from scratch."
+}