loki-mode 7.87.0 → 7.88.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.87.0
+# Loki Mode v7.88.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.87.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.88.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.87.0
+7.88.0

package/autonomy/lib/own-render.py

@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+"""Finish-and-own renderer for Loki Mode (Loop 5, v7.88.0).
+
+A PURE render layer over EXISTING honest data. It reads the artifacts the
+runner already wrote (the Evidence Receipt proof.json, completion.json,
+USAGE.md, the app-runner state, the assumptions ledger) and restates them in
+plain English for a NON-technical founder.
+
+Design rules (LOOP5-FINISH-AND-OWN-PLAN.md):
+  - NEVER recompute or fabricate. Every line maps to a real artifact value.
+  - The "Is it working?" verdict is taken VERBATIM from honesty.headline.
+    Green ("ready") is gated on headline == "VERIFIED" AND tests passed AND
+    the build ran. This honesty gate is the core of the lib.
+  - Tolerant of missing artifacts: each one absent is marked honestly rather
+    than guessed at.
+  - No LLM call here (keep it pure / deterministic / testable). The "What you
+    have now" paragraph is a deterministic template over the recorded brief +
+    diff stat. No invented features.
+  - Exit 0 always: this is a report, never a gate.
+
+CLI:
+  python3 autonomy/lib/own-render.py [--loki-dir .loki] [--md|--json]
+"""
+
+import argparse
+import json
+import os
+import sys
+
+
+# ---------------------------------------------------------------------------
+# tolerant readers
+# ---------------------------------------------------------------------------
+
+def _read_json(path, default=None):
+    try:
+        with open(path, "r") as f:
+            return json.load(f)
+    except Exception:
+        return default
+
+
+def _read_text(path, default=""):
+    try:
+        with open(path, "r", errors="replace") as f:
+            return f.read()
+    except Exception:
+        return default
+
+
+def _latest_proof(loki_dir):
+    """Return (run_id, proof_dict) for the most recent proof, or (None, None).
+
+    Proof run dirs are named with a timestamp prefix (YYYYmmddTHHMMSSZ-...),
+    so a lexicographic sort puts the newest last. We pick the newest dir that
+    actually contains a readable proof.json.
+    """
+    proofs_dir = os.path.join(loki_dir, "proofs")
+    try:
+        entries = sorted(os.listdir(proofs_dir))
+    except Exception:
+        return None, None
+    for run_id in reversed(entries):
+        proof = _read_json(os.path.join(proofs_dir, run_id, "proof.json"))
+        if isinstance(proof, dict):
+            return run_id, proof
+    return None, None
+
+
+def _live_url(loki_dir):
+    """Return the live app URL only when the app runner reports it running."""
+    state = _read_json(os.path.join(loki_dir, "app-runner", "state.json"))
+    if isinstance(state, dict) and state.get("status") == "running":
+        url = str(state.get("url") or "").strip()
+        if url:
+            return url
+    return ""
+
+
+def _usage_section(usage_text, header):
+    """Pull the body of a '## <header>' section from USAGE.md, verbatim.
+
+    Returns the lines under the matching heading up to the next '## ' heading,
+    trimmed of blank edges. Empty string when the section is absent.
+    """
+    if not usage_text:
+        return ""
+    lines = usage_text.splitlines()
+    out = []
+    capturing = False
+    want = header.strip().lower()
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("## "):
+            if capturing:
+                break
+            name = stripped[3:].strip().lower()
+            # Match on a prefix so "## Verify (it works)" matches "Verify".
+            capturing = name == want or name.startswith(want + " ") \
+                or name.startswith(want + " (")
+            continue
+        if capturing:
+            out.append(line)
+    # Trim leading/trailing blank lines.
+    while out and not out[0].strip():
+        out.pop(0)
+    while out and not out[-1].strip():
+        out.pop()
+    return "\n".join(out)
+
+
+# ---------------------------------------------------------------------------
+# honesty gate (the core)
+# ---------------------------------------------------------------------------
+
+def _is_ready(proof):
+    """Deterministic green gate. True ONLY when:
+      - honesty.headline == "VERIFIED", AND
+      - facts.tests.status in (passed, verified), AND
+      - the build actually ran (facts.build.ran true / status not 'not_run').
+
+    Any one missing -> not ready. This is the line that must never overclaim.
+    """
+    if not isinstance(proof, dict):
+        return False
+    honesty = proof.get("honesty") or {}
+    if str(honesty.get("headline") or "").strip().upper() != "VERIFIED":
+        return False
+    facts = proof.get("facts") or {}
+    tests = facts.get("tests") or {}
+    if str(tests.get("status") or "").strip().lower() not in ("passed", "verified"):
+        return False
+    build = facts.get("build") or {}
+    build_ran = bool(build.get("ran")) or \
+        str(build.get("status") or "").strip().lower() not in ("not_run", "", "none")
+    return build_ran
+
+
+# ---------------------------------------------------------------------------
+# section builders (markdown). Each returns a list of lines.
+# ---------------------------------------------------------------------------
+
+def _section_what_you_have(proof):
+    """1. 'What you have now' - product-terms restatement of the brief + diff.
+
+    Deterministic template only: the recorded brief verbatim plus a one-line
+    files-changed summary. No invented features, no LLM call.
+    """
+    lines = ["## What you have now", ""]
+    spec = (proof or {}).get("spec") or {}
+    brief = str(spec.get("brief") or "").strip()
+    if brief:
+        # Restate the brief as the description of what was built. Quote it so the
+        # reader sees it is their own words, not a Loki claim.
+        first = brief.splitlines()[0].strip()
+        lines.append("You asked Loki to build this:")
+        lines.append("")
+        lines.append("> " + first)
+    else:
+        lines.append("Loki worked directly on an existing codebase here (no written "
+                     "spec was recorded for this run).")
+    lines.append("")
+
+    facts = (proof or {}).get("facts") or {}
+    git = facts.get("git") or {}
+    diff = git.get("diff") or (proof or {}).get("files_changed") or {}
+    count = diff.get("count") or 0
+    ins = diff.get("insertions") or 0
+    dele = diff.get("deletions") or 0
+    if count:
+        lines.append("It changed %d file%s (%d lines added, %d removed)."
+                     % (count, "" if count == 1 else "s", ins, dele))
+    else:
+        lines.append("No file changes were recorded for this run.")
+    return lines
+
+
+def _build_age_note(run_id):
+    """An honest 'this verdict describes the build at <when>' line + a pointer to
+    re-verify against current code. A non-technical owner must not read an old
+    receipt as a statement about code they edited since the build."""
+    lines = []
+    when = _run_id_when(run_id)
+    if when:
+        lines.append("This describes the build Loki finished on %s. If you (or a "
+                     "developer) changed the code after that, this verdict is about "
+                     "the older version, not your current files." % when)
+    else:
+        lines.append("This describes the last build Loki finished. If the code "
+                     "changed since then, this verdict is about the older version.")
+    if run_id:
+        lines.append("To confirm it still matches your current code, run: "
+                     "`loki proof verify %s`" % run_id)
+    return lines
+
+
+def _run_id_when(run_id):
+    """Format a human date from a proof run_id (YYYYmmddTHHMMSSZ-...). Returns ''
+    if the id is not in that shape (no fabrication -- only restate what is there)."""
+    if not run_id:
+        return ""
+    stamp = str(run_id).split("-", 1)[0]
+    # Expect YYYYmmddTHHMMSSZ
+    if len(stamp) >= 16 and stamp[8:9] == "T" and stamp[15:16] == "Z":
+        y, mo, d = stamp[0:4], stamp[4:6], stamp[6:8]
+        hh, mm = stamp[9:11], stamp[11:13]
+        if y.isdigit() and mo.isdigit() and d.isdigit():
+            return "%s-%s-%s at %s:%s UTC" % (y, mo, d, hh, mm)
+    return ""
+
+
+def _section_is_it_working(proof, run_id=None):
+    """2. 'Is it working?' - VERBATIM honesty.headline gating.
+
+    Green only when _is_ready(). Otherwise plainly states what was not verified
+    and lists honesty.degraded[]. NEVER prints a ready/ship line unless ready.
+    Always dates the verdict + points to re-verify, so a stale receipt is never
+    read as current truth.
+    """
+    lines = ["## Is it working?", ""]
+    honesty = (proof or {}).get("honesty") or {}
+    headline = str(honesty.get("headline") or "").strip()
+    degraded = honesty.get("degraded") or []
+
+    if _is_ready(proof):
+        lines.append("Yes. Loki verified this build: the tests passed and the "
+                     "build ran cleanly.")
+        lines.append("")
+        lines.append("Verdict (Loki's honest receipt): %s" % (headline or "VERIFIED"))
+        lines.append("")
+        lines.extend(_build_age_note(run_id))
+        return lines
+
+    # Not ready. State the verdict plainly and list every gap.
+    if headline:
+        lines.append("Not fully verified. Loki's honest verdict for this run is: "
+                     "%s" % headline)
+    else:
+        lines.append("Not verified. Loki did not record a verdict for this run.")
+    lines.append("")
+    lines.append("This means Loki is NOT telling you it is ready to ship. Here is "
+                 "what was not verified:")
+    lines.append("")
+    if isinstance(degraded, list) and degraded:
+        for d in degraded:
+            if isinstance(d, dict):
+                item = str(d.get("item") or "").strip() or "(unnamed check)"
+                status = str(d.get("status") or "").strip()
+                reason = str(d.get("reason") or "").strip()
+                bits = [b for b in (status, reason) if b]
+                tail = (" - " + "; ".join(bits)) if bits else ""
+                lines.append("- %s%s" % (item, tail))
+            else:
+                lines.append("- %s" % str(d))
+    else:
+        lines.append("- (no specific gaps were itemized, but the verdict above is "
+                     "not a clean pass)")
+    lines.append("")
+    lines.extend(_build_age_note(run_id))
+    return lines
+
+
+def _section_run_on_computer(proof, usage_text, live_url):
+    """3. 'How to run it on your computer' - quote Start/Verify from USAGE.md."""
+    lines = ["## How to run it on your computer", ""]
+    if live_url:
+        lines.append("It is running right now on this machine at: %s" % live_url)
+        lines.append("")
+    start = _usage_section(usage_text, "Start")
+    verify = _usage_section(usage_text, "Verify")
+    install = _usage_section(usage_text, "Install")
+    if install:
+        lines.append("First, install it:")
+        lines.append("")
+        lines.append("```")
+        lines.append(install)
+        lines.append("```")
+        lines.append("")
+    if start:
+        lines.append("To start it:")
+        lines.append("")
+        lines.append("```")
+        lines.append(start)
+        lines.append("```")
+        lines.append("")
+    if verify:
+        lines.append("To check it works:")
+        lines.append("")
+        lines.append("```")
+        lines.append(verify)
+        lines.append("```")
+    if not (start or verify or install):
+        lines.append("No run instructions (USAGE.md) were found for this build. "
+                     "Once you run a build to completion, Loki writes a USAGE.md at "
+                     "the project root with the exact commands.")
+    return lines
+
+
+def _section_put_online(proof):
+    """4. 'How to put it online' - mention loki deploy / preview; URL if present."""
+    lines = ["## How to put it online", ""]
+    deployment = (proof or {}).get("deployment") or {}
+    deployed_url = str(deployment.get("deployed_url") or "").strip()
+    if deployed_url:
+        lines.append("This build was deployed. It is live at: %s" % deployed_url)
+        lines.append("")
+    else:
+        lines.append("This build has not been put online yet.")
+        lines.append("")
+    lines.append("When you are ready, you have two options:")
+    lines.append("")
+    lines.append("- `loki deploy` - deploy it using your own cloud account.")
+    lines.append("- `loki preview --public` - share a temporary public link to the "
+                 "version running on your computer.")
+    return lines
+
+
+def _section_developer_needs(proof):
+    """5. 'What a developer needs to know' - group changed files by top dir."""
+    lines = ["## What a developer needs to know", ""]
+    facts = (proof or {}).get("facts") or {}
+    git = facts.get("git") or {}
+    diff = git.get("diff") or (proof or {}).get("files_changed") or {}
+    files = diff.get("files") or []
+    if isinstance(files, list) and files:
+        groups = {}
+        for f in files:
+            if not isinstance(f, dict):
+                continue
+            path = str(f.get("path") or "").strip()
+            if not path:
+                continue
+            top = path.split("/")[0] if "/" in path else "(project root)"
+            groups.setdefault(top, 0)
+            groups[top] += 1
+        if groups:
+            lines.append("The changes touch these areas of the codebase:")
+            lines.append("")
+            for top in sorted(groups):
+                n = groups[top]
+                lines.append("- %s (%d file%s)" % (top, n, "" if n == 1 else "s"))
+            lines.append("")
+    else:
+        lines.append("No changed-file list was recorded for this run.")
+        lines.append("")
+    lines.append("A developer should read USAGE.md (run/verify commands) and the "
+                 "developer handoff notes in .loki/memory/handoffs/.")
+    return lines
+
+
+def _section_verified(proof, run_id):
+    """6. 'What is verified' - the proof commands."""
+    lines = ["## What is verified", ""]
+    if run_id:
+        lines.append("Loki keeps a tamper-evident receipt of exactly what it did. "
+                     "Anyone can inspect or re-check it:")
+        lines.append("")
+        lines.append("- `loki proof show %s` - read the full receipt." % run_id)
+        lines.append("- `loki proof verify %s` - confirm the receipt has not been "
+                     "altered." % run_id)
+    else:
+        lines.append("No receipt was found for this project yet. Loki writes one "
+                     "when a build completes.")
+    return lines
+
+
+def _section_still_to_do(proof, completion):
+    """7. 'What you still need to do or decide'."""
+    lines = ["## What you still need to do or decide", ""]
+    items = []
+
+    # Assumptions Loki had to make where the spec was ambiguous.
+    total = 0
+    high = 0
+    if isinstance(completion, dict):
+        try:
+            total = int(completion.get("assumptions_total") or 0)
+        except Exception:
+            total = 0
+        try:
+            high = int(completion.get("assumptions_high") or 0)
+        except Exception:
+            high = 0
+    if total > 0:
+        msg = ("Review %d assumption%s Loki had to make where your spec was "
+               "ambiguous" % (total, "" if total == 1 else "s"))
+        if high > 0:
+            msg += (" (%d of them high-impact)" % high)
+        msg += ". See .loki/assumptions/ledger.md."
+        items.append(msg)
+
+    # Anything not verified (degraded items) is also a to-do.
+    honesty = (proof or {}).get("honesty") or {}
+    degraded = honesty.get("degraded") or []
+    if isinstance(degraded, list) and degraded:
+        for d in degraded:
+            if isinstance(d, dict):
+                item = str(d.get("item") or "").strip()
+                reason = str(d.get("reason") or "").strip()
+                if item:
+                    items.append("Address: %s%s"
+                                 % (item, (" (" + reason + ")") if reason else ""))
+
+    # PR state.
+    pr_url = ""
+    if isinstance(completion, dict):
+        pr_url = str(completion.get("pr_url") or "").strip()
+    if pr_url:
+        items.append("A pull request was opened: %s" % pr_url)
+    else:
+        items.append("No pull request was opened. Open one when you are ready to "
+                     "merge the changes.")
+
+    # Deployment state.
+    deployment = (proof or {}).get("deployment") or {}
+    if not str(deployment.get("deployed_url") or "").strip():
+        items.append("It is not deployed yet. Use `loki deploy` when you are ready.")
+
+    for it in items:
+        lines.append("- %s" % it)
+    if not items:
+        lines.append("- Nothing outstanding was recorded. Read the sections above "
+                     "to decide your next step.")
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# top-level render
+# ---------------------------------------------------------------------------
+
+def _empty_doc_md(loki_dir):
+    return "\n".join([
+        "# What Loki built for you",
+        "",
+        "No completed build was found here yet.",
+        "",
+        "Run `loki start <spec>` to build something (a one-line idea, a PRD "
+        "file, or a GitHub issue all work). When it finishes, come back and run "
+        "`loki own` to read this plain-English summary of what you have.",
+        "",
+    ])
+
+
+def _empty_doc_json(loki_dir):
+    return {
+        "ok": True,
+        "found": False,
+        "loki_dir": loki_dir,
+        "message": "No completed build found here yet -- run loki start <spec>",
+    }
+
+
+def render_markdown(loki_dir):
+    run_id, proof = _latest_proof(loki_dir)
+    if proof is None:
+        return _empty_doc_md(loki_dir)
+
+    completion = _read_json(os.path.join(loki_dir, "state", "completion.json"))
+    # USAGE.md lives at the project root (parent of .loki).
+    project_root = os.path.dirname(os.path.abspath(loki_dir)) or "."
+    usage_text = _read_text(os.path.join(project_root, "USAGE.md"))
+    live_url = _live_url(loki_dir)
+
+    blocks = [["# What Loki built for you", ""]]
+    blocks.append(_section_what_you_have(proof))
+    blocks.append(_section_is_it_working(proof, run_id))
+    blocks.append(_section_run_on_computer(proof, usage_text, live_url))
+    blocks.append(_section_put_online(proof))
+    blocks.append(_section_developer_needs(proof))
+    blocks.append(_section_verified(proof, run_id))
+    blocks.append(_section_still_to_do(proof, completion))
+
+    parts = []
+    for b in blocks:
+        parts.append("\n".join(b))
+    return "\n\n".join(parts) + "\n"
+
+
+def render_json(loki_dir):
+    run_id, proof = _latest_proof(loki_dir)
+    if proof is None:
+        return _empty_doc_json(loki_dir)
+
+    completion = _read_json(os.path.join(loki_dir, "state", "completion.json")) or {}
+    project_root = os.path.dirname(os.path.abspath(loki_dir)) or "."
+    usage_text = _read_text(os.path.join(project_root, "USAGE.md"))
+    live_url = _live_url(loki_dir)
+
+    honesty = proof.get("honesty") or {}
+    deployment = proof.get("deployment") or {}
+    facts = proof.get("facts") or {}
+    git = facts.get("git") or {}
+    diff = git.get("diff") or proof.get("files_changed") or {}
+
+    return {
+        "ok": True,
+        "found": True,
+        "run_id": run_id,
+        "ready": _is_ready(proof),
+        "headline": str(honesty.get("headline") or ""),
+        "degraded": honesty.get("degraded") or [],
+        "spec_brief": str((proof.get("spec") or {}).get("brief") or ""),
+        "files_changed": {
+            "count": diff.get("count") or 0,
+            "insertions": diff.get("insertions") or 0,
+            "deletions": diff.get("deletions") or 0,
+        },
+        "live_url": live_url,
+        "deployed_url": str(deployment.get("deployed_url") or ""),
+        "start_command": _usage_section(usage_text, "Start"),
+        "verify_command": _usage_section(usage_text, "Verify"),
+        "pr_url": str(completion.get("pr_url") or ""),
+        "assumptions_total": completion.get("assumptions_total") or 0,
+        "assumptions_high": completion.get("assumptions_high") or 0,
+        "proof_show_cmd": ("loki proof show %s" % run_id) if run_id else "",
+        "proof_verify_cmd": ("loki proof verify %s" % run_id) if run_id else "",
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Loki Mode finish-and-own renderer (plain-English ownership doc)"
+    )
+    parser.add_argument("--loki-dir", default=".loki")
+    fmt = parser.add_mutually_exclusive_group()
+    fmt.add_argument("--md", action="store_const", const="md", dest="fmt")
+    fmt.add_argument("--json", action="store_const", const="json", dest="fmt")
+    parser.set_defaults(fmt="md")
+    args = parser.parse_args(argv)
+
+    loki_dir = os.path.abspath(args.loki_dir)
+    try:
+        if args.fmt == "json":
+            print(json.dumps(render_json(loki_dir), indent=2))
+        else:
+            print(render_markdown(loki_dir))
+    except Exception as exc:
+        # This is a report, never a gate: emit an honest line and exit 0.
+        if args.fmt == "json":
+            print(json.dumps({"ok": False, "found": False, "error": str(exc)}))
+        else:
+            sys.stderr.write("warn: own-render failed: %s\n" % exc)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/autonomy/loki

@@ -16504,6 +16504,12 @@ main() {
             # Secure-by-default gate surface: inspect findings + manage waivers.
             cmd_secure "$@"
             ;;
+        own|handoff)
+            # Finish-and-own: a plain-English ownership handoff for a non-technical
+            # owner (what was built, is it working, how to run/deploy, what is left).
+            # `loki handoff` is an alias for `loki own`.
+            cmd_own "$@"
+            ;;
         bench)
             cmd_bench "$@"
             ;;
@@ -30438,6 +30444,60 @@ cmd_bench() {
     bash "$bench_sh" "$@"
 }
 
+# loki own - finish-and-own (v7.88.0): a plain-English ownership handoff for a
+# NON-technical owner. A pure render (autonomy/lib/own-render.py) over the data
+# Loki already captured -- the Evidence Receipt, the completion summary, and
+# USAGE.md -- so it cannot fabricate: the "is it working?" verdict comes verbatim
+# from the receipt's honest headline and is never green unless the receipt is
+# VERIFIED. Default prints the doc; --md writes HANDOFF.md; --json for tooling.
+# `loki handoff` is an alias.
+cmd_own() {
+    local renderer="${_LOKI_SCRIPT_DIR}/lib/own-render.py"
+    if [ ! -f "$renderer" ]; then
+        echo -e "${RED}Finish-and-own renderer not found (autonomy/lib/own-render.py).${NC}" >&2
+        exit 2
+    fi
+    case "${1:-}" in
+        --help|-h|help)
+            echo -e "${BOLD}loki own${NC} - a plain-English ownership handoff (alias: loki handoff)"
+            echo ""
+            echo "Usage: loki own [--md | --json]"
+            echo ""
+            echo "Explains, in plain language for a non-technical owner: what was"
+            echo "built, whether Loki verified it works, how to run it, how to put"
+            echo "it online, what a developer needs to know, and what is left to do."
+            echo "It reads the last build's Evidence Receipt + completion summary;"
+            echo "the 'is it working' verdict is the receipt's honest headline (never"
+            echo "green unless the build is VERIFIED)."
+            echo ""
+            echo "Options:"
+            echo "  --md     Write HANDOFF.md to the project root"
+            echo "  --json   Emit the structured handoff as JSON"
+            exit 0
+            ;;
+    esac
+    # --md writes HANDOFF.md at the project root (matches the help). The renderer
+    # prints markdown on stdout; the CLI places it as a file, atomically (temp+mv)
+    # so a partial write never leaves a truncated HANDOFF.md. Any other args
+    # (--json, default) pass through and print.
+    if [ "${1:-}" = "--md" ]; then
+        local _handoff="${TARGET_DIR:-.}/HANDOFF.md"
+        local _handoff_tmp="${TARGET_DIR:-.}/.HANDOFF.md.tmp"
+        if python3 "$renderer" --loki-dir "${LOKI_DIR:-.loki}" --md > "$_handoff_tmp" 2>/dev/null; then
+            mv -f "$_handoff_tmp" "$_handoff" && \
+                echo -e "${GREEN}Wrote ${_handoff}${NC} - open it or hand it to whoever owns this build." || \
+                { rm -f "$_handoff_tmp" 2>/dev/null; echo -e "${RED}Could not write HANDOFF.md${NC}" >&2; exit 1; }
+        else
+            rm -f "$_handoff_tmp" 2>/dev/null
+            echo -e "${RED}Could not render the ownership handoff${NC}" >&2
+            exit 1
+        fi
+        exit 0
+    fi
+    python3 "$renderer" --loki-dir "${LOKI_DIR:-.loki}" "$@"
+    exit $?
+}
+
 # loki secure - the secure-by-default gate surface (v7.87.0).
 # Subcommands: list (show findings) | waive <rule> <file> [reason] | unwaive.
 # Waivers are written to .loki/quality/security-waivers.json, which the gate

package/autonomy/run.sh

@@ -17367,6 +17367,30 @@ main() {
         generate_proof_of_run "$result" || true
     fi
 
+    # Finish-and-own (v7.88.0): write a plain-English ownership handoff
+    # (HANDOFF.md) for a non-technical owner. Runs AFTER the proof so the
+    # "is it working?" verdict reads the receipt's honest headline. Default-on,
+    # opt out with LOKI_HANDOFF=0. Fire-and-forget: best-effort, never blocks
+    # completion (same contract as the proof + usage-regen). A pure render over
+    # the proof + completion + USAGE.md, so it cannot fabricate.
+    if [ "${LOKI_HANDOFF:-1}" != "0" ]; then
+        local _own_render="$SCRIPT_DIR/lib/own-render.py"
+        if [ -f "$_own_render" ] && command -v python3 >/dev/null 2>&1; then
+            # The renderer prints the plain-English doc on stdout (--md); the hook
+            # places it at the project root as HANDOFF.md. Write to a temp then
+            # move, so a partial write never leaves a truncated HANDOFF.md.
+            local _handoff_dir _handoff_md _handoff_tmp
+            _handoff_dir="${TARGET_DIR:-.}"
+            _handoff_md="$_handoff_dir/HANDOFF.md"
+            _handoff_tmp="$_handoff_dir/.HANDOFF.md.tmp"
+            if python3 "$_own_render" --loki-dir "$LOKI_DIR" --md > "$_handoff_tmp" 2>/dev/null; then
+                mv -f "$_handoff_tmp" "$_handoff_md" 2>/dev/null || rm -f "$_handoff_tmp" 2>/dev/null || true
+            else
+                rm -f "$_handoff_tmp" 2>/dev/null || true
+            fi
+        fi
+    fi
+
     # R7 (zero-config first run): "what next / go deeper" framing. Only when the
     # CLI flagged this as a TTFV first run and stdout is a TTY, so it stays
     # silent in CI / pipes and never fires for normal PRD runs. The wording

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.87.0"
+__version__ = "7.88.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.87.0
+**Version:** v7.88.0
 
 ---
 
@@ -395,7 +395,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.87.0 start ./my-spec.md
+  asklokesh/loki-mode:7.88.0 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.87.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,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,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 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 s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){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 e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
+var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.88.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,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,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 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 s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){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 e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -796,4 +796,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($Q),2}}s1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var qZ=await KZ(Bun.argv.slice(2));process.exit(qZ);
 
-//# debugId=7982E696DB64940A64756E2164756E21
+//# debugId=65E93B4739145ECE64756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.87.0",
+  "version": "7.88.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.87.0",
+  "version": "7.88.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",