loki-mode 6.81.0 → 6.82.0

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with minimal human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v6.81.0
+# Loki Mode v6.82.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -269,4 +269,4 @@ The following features are documented in skill modules but not yet fully automat
 | Quality gates 3-reviewer system | Implemented (v5.35.0) | 5 specialist reviewers in `skills/quality-gates.md`; execution in run.sh |
 | Benchmarks (HumanEval, SWE-bench) | Infrastructure only | Runner scripts and datasets exist in `benchmarks/`; no published results |
 
-**v6.81.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v6.82.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.81.0
+6.82.0

package/autonomy/loki

@@ -522,6 +522,7 @@ cmd_start() {
     local mirofish_docker_image=""
     local mirofish_bg=false
     local mirofish_disabled=false
+    local no_plan=false  # v6.81.1: --no-plan opts out of auto-plan display
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
@@ -554,6 +555,7 @@ cmd_start() {
                 echo "  --mirofish-timeout S  Max pipeline wait in seconds (default: 3600)"
                 echo "  --mirofish-bg         Run MiroFish pipeline in background"
                 echo "  --no-mirofish         Disable MiroFish even if env var is set"
+                echo "  --no-plan             Skip auto-shown PRD analysis at startup"
                 echo "  --yes, -y             Skip confirmation prompts (auto-confirm)"
                 echo ""
                 echo "Environment Variables:"
@@ -776,6 +778,10 @@ cmd_start() {
                 mirofish_disabled=true
                 shift
                 ;;
+            --no-plan)
+                no_plan=true
+                shift
+                ;;
             --budget)
                 if [[ -n "${2:-}" ]]; then
                     if ! echo "$2" | grep -qE '^[0-9]+(\.[0-9]+)?$'; then
@@ -1032,6 +1038,13 @@ cmd_start() {
         fi
     fi
 
+    # v6.81.1: auto-show PRD analysis so users see complexity / cost / time
+    # up front without needing a separate `loki plan` invocation. Skipped via
+    # --no-plan or in non-TTY contexts (CI/pipe). No-op when PRD is absent.
+    if [ -n "$prd_file" ]; then
+        maybe_show_auto_plan "$prd_file" "$no_plan" || true
+    fi
+
     # Load saved provider if not specified on command line
     if [ -z "$provider" ]; then
         if [ -f "$LOKI_DIR/state/provider" ]; then
@@ -4083,6 +4096,7 @@ cmd_run() {
                 echo "  --complex          Force complex complexity tier"
                 echo "  --no-dashboard     Disable web dashboard"
                 echo "  --sandbox          Run in Docker sandbox"
+                echo "  --no-plan          Skip auto-shown PRD analysis at startup"
                 echo "  --budget USD       Set cost budget limit"
                 echo ""
                 echo "Progressive Isolation:"
@@ -4155,7 +4169,7 @@ cmd_run() {
                 start_args+=("--provider" "$provider_override")
                 shift
                 ;;
-            --parallel|--bg|--background|--simple|--complex|--no-dashboard|--sandbox)
+            --parallel|--bg|--background|--simple|--complex|--no-dashboard|--sandbox|--no-plan)
                 start_args+=("$1")
                 shift
                 ;;
@@ -4394,6 +4408,29 @@ INNER_SCRIPT_EOF
     echo "$prd_content" > "$output_file"
     echo -e "${GREEN}PRD generated:${NC} $output_file"
 
+    # v6.81.1: auto-show PRD analysis once the issue-derived PRD is on disk,
+    # so users see cost / complexity / time before execution begins. When the
+    # user will continue into `cmd_start` below, cmd_start also has its own
+    # auto-plan call -- but that second call respects --no-plan / TTY checks
+    # and would typically re-emit the same analysis. We therefore pass
+    # --no-plan along in start_args to prevent duplicate output. Passing
+    # --no-plan here is safe because `cmd_run` itself already displayed the
+    # plan.
+    local _run_no_plan=false
+    for _arg in "${start_args[@]+"${start_args[@]}"}"; do
+        if [[ "$_arg" == "--no-plan" ]]; then
+            _run_no_plan=true
+            break
+        fi
+    done
+    if [ -f "$output_file" ]; then
+        maybe_show_auto_plan "$output_file" "$_run_no_plan" || true
+    fi
+    # Ensure cmd_start does not re-show the plan now that we just did.
+    if [[ "$_run_no_plan" != "true" ]]; then
+        start_args+=("--no-plan")
+    fi
+
     # Start Loki Mode unless --no-start
     if [[ "$no_start" == "true" ]]; then
         echo ""
@@ -10524,58 +10561,25 @@ with open('$failover_file', 'w') as f: json.dump(d, f, indent=2)
     done
 }
 
-# Dry-run PRD analysis and cost estimation (v6.18.0)
-cmd_plan() {
-    local prd_file=""
-    local show_json=false
-    local show_verbose=false
-
-    while [[ $# -gt 0 ]]; do
-        case "$1" in
-            --help|-h)
-                echo -e "${BOLD}loki plan${NC} - Dry-run PRD analysis and cost estimation"
-                echo ""
-                echo "Usage: loki plan <PRD> [options]"
-                echo ""
-                echo "Analyzes a PRD file without executing anything. Outputs complexity,"
-                echo "estimated iterations, token usage, cost, and execution plan."
-                echo ""
-                echo "Options:"
-                echo "  --json        Machine-readable JSON output"
-                echo "  --verbose     Show detailed per-iteration breakdown"
-                echo "  --help, -h    Show this help"
-                echo ""
-                echo "Examples:"
-                echo "  loki plan ./prd.md"
-                echo "  loki plan ./prd.md --json"
-                echo "  loki plan ./prd.md --verbose"
-                return 0
-                ;;
-            --json) show_json=true; shift ;;
-            --verbose) show_verbose=true; shift ;;
-            *)
-                if [ -z "$prd_file" ]; then
-                    prd_file="$1"
-                fi
-                shift
-                ;;
-        esac
-    done
-
-    if [ -z "$prd_file" ]; then
-        echo -e "${RED}Usage: loki plan <PRD file>${NC}"
-        echo "Run 'loki plan --help' for usage."
+# Reusable PRD plan analysis (v6.81.1)
+# Shared by `loki plan`, `loki start` (auto-plan), and `loki run` (auto-plan).
+# Arguments:
+#   $1 - absolute PRD path
+#   $2 - show_json (true|false)
+#   $3 - show_verbose (true|false)
+# Respects:
+#   LOKI_SESSION_MODEL          - Pins ALL iterations to one tier (default: sonnet)
+#   LOKI_LEGACY_TIER_SWITCHING  - When 'true', restores per-iteration rotation
+show_prd_plan() {
+    local prd_path="$1"
+    local show_json="${2:-false}"
+    local show_verbose="${3:-false}"
+
+    if [ -z "$prd_path" ] || [ ! -f "$prd_path" ]; then
+        echo -e "${RED}show_prd_plan: PRD file not found: $prd_path${NC}" >&2
         return 1
     fi
 
-    if [ ! -f "$prd_file" ]; then
-        echo -e "${RED}PRD file not found: $prd_file${NC}"
-        return 1
-    fi
-
-    local prd_path
-    prd_path="$(cd "$(dirname "$prd_file")" && pwd)/$(basename "$prd_file")"
-
     python3 -c "
 import json, sys, os, re, math
 
@@ -10583,6 +10587,22 @@ prd_path = sys.argv[1]
 show_json = sys.argv[2] == 'true'
 show_verbose = sys.argv[3] == 'true'
 
+# v6.81.1: Respect LOKI_SESSION_MODEL (pinned by v6.81.0) so the estimate
+# matches what the main loop actually invokes. LOKI_LEGACY_TIER_SWITCHING=true
+# restores the legacy per-iteration Opus/Sonnet/Haiku rotation for users who
+# explicitly opt out.
+session_model_env = (os.environ.get('LOKI_SESSION_MODEL', 'sonnet') or 'sonnet').strip().lower()
+legacy_tier_switching = (os.environ.get('LOKI_LEGACY_TIER_SWITCHING', 'false') or 'false').strip().lower() == 'true'
+
+# Map session model name to tier key used in tokens_per_tier below.
+# Unknown models fall through to 'development' (Sonnet) as a safe default.
+_session_tier_map = {
+    'opus': 'planning',
+    'sonnet': 'development',
+    'haiku': 'fast',
+}
+session_tier = _session_tier_map.get(session_model_env, 'development')
+
 # Colors (disabled for JSON mode)
 if show_json:
     RED = GREEN = YELLOW = BLUE = CYAN = BOLD = DIM = NC = ''
@@ -10770,18 +10790,28 @@ tier_iterations = {'Opus': 0, 'Sonnet': 0, 'Haiku': 0}
 for i in range(estimated_iterations):
     rarv_step = i % 4
     if rarv_step == 0:
-        tier = 'planning'
         phase_label = 'Reason (Planning)'
     elif rarv_step == 1:
-        tier = 'development'
         phase_label = 'Act (Implementation)'
     elif rarv_step == 2:
-        tier = 'development'
         phase_label = 'Reflect (Review)'
     else:
-        tier = 'fast'
         phase_label = 'Verify (Testing)'
 
+    if legacy_tier_switching:
+        # Legacy pre-v6.81.0 behavior: rotate tier per RARV step.
+        if rarv_step == 0:
+            tier = 'planning'
+        elif rarv_step in (1, 2):
+            tier = 'development'
+        else:
+            tier = 'fast'
+    else:
+        # v6.81.0+: main loop is pinned to LOKI_SESSION_MODEL. Estimate
+        # MUST use the same tier for all iterations to avoid quoting a
+        # cost higher than the user will actually pay.
+        tier = session_tier
+
     info = tokens_per_tier[tier]
     model = info['model']
     inp = info['input']
@@ -10957,7 +10987,20 @@ print(f'  RARV cycles: {cycle_count} (4 iterations per cycle)')
 opus_n = tier_iterations.get('Opus', 0)
 sonnet_n = tier_iterations.get('Sonnet', 0)
 haiku_n = tier_iterations.get('Haiku', 0)
-print(f'  Model distribution: Opus x{opus_n} | Sonnet x{sonnet_n} | Haiku x{haiku_n}')
+if legacy_tier_switching:
+    print(f'  Model distribution: Opus x{opus_n} | Sonnet x{sonnet_n} | Haiku x{haiku_n}')
+    print(f'  {DIM}(legacy rotation: LOKI_LEGACY_TIER_SWITCHING=true){NC}')
+else:
+    # Session-pinned: exactly one tier has all iterations.
+    pinned_parts = []
+    if opus_n > 0:
+        pinned_parts.append(f'Opus x{opus_n}')
+    if sonnet_n > 0:
+        pinned_parts.append(f'Sonnet x{sonnet_n}')
+    if haiku_n > 0:
+        pinned_parts.append(f'Haiku x{haiku_n}')
+    print('  Model distribution: ' + (' | '.join(pinned_parts) if pinned_parts else '(none)'))
+    print(f'  {DIM}(pinned via LOKI_SESSION_MODEL={session_model_env}; set LOKI_LEGACY_TIER_SWITCHING=true to rotate){NC}')
 
 # Tokens
 total_tok = total_input_tokens + total_output_tokens
@@ -10971,6 +11014,11 @@ ds = chr(36)  # dollar sign
 print(f'\n{CYAN}Cost Estimate{NC}')
 print(f'  {BOLD}Total: {ds}{total_cost:.2f}{NC}')
 for model in ['Opus', 'Sonnet', 'Haiku']:
+    # v6.81.1: suppress zero-cost tiers (e.g. session-pinned runs). Keeps
+    # the breakdown focused on models actually used. Legacy mode still
+    # shows all three because each tier has non-zero iterations.
+    if tier_iterations.get(model, 0) == 0 and tier_totals.get(model, 0) == 0:
+        continue
     pct = (tier_totals[model] / total_cost * 100) if total_cost > 0 else 0
     bar_len = int(pct / 5)
     bar = '#' * bar_len + '.' * (20 - bar_len)
@@ -11025,6 +11073,99 @@ print()
 " "$prd_path" "$show_json" "$show_verbose"
 }
 
+# Dry-run PRD analysis and cost estimation (v6.18.0; refactored v6.81.1)
+# Thin wrapper around show_prd_plan() so the same analysis is reusable from
+# `loki start`, `loki run`, and other commands without duplicated code.
+cmd_plan() {
+    local prd_file=""
+    local show_json=false
+    local show_verbose=false
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo -e "${BOLD}loki plan${NC} - Dry-run PRD analysis and cost estimation"
+                echo ""
+                echo "Usage: loki plan <PRD> [options]"
+                echo ""
+                echo "Analyzes a PRD file without executing anything. Outputs complexity,"
+                echo "estimated iterations, token usage, cost, and execution plan."
+                echo ""
+                echo "Options:"
+                echo "  --json        Machine-readable JSON output"
+                echo "  --verbose     Show detailed per-iteration breakdown"
+                echo "  --help, -h    Show this help"
+                echo ""
+                echo "Environment Variables:"
+                echo "  LOKI_SESSION_MODEL            Pin cost estimate to a single tier"
+                echo "                                (opus|sonnet|haiku, default: sonnet)"
+                echo "  LOKI_LEGACY_TIER_SWITCHING    Set to 'true' to restore the legacy"
+                echo "                                Opus/Sonnet/Haiku per-iteration rotation"
+                echo ""
+                echo "Examples:"
+                echo "  loki plan ./prd.md"
+                echo "  loki plan ./prd.md --json"
+                echo "  loki plan ./prd.md --verbose"
+                return 0
+                ;;
+            --json) show_json=true; shift ;;
+            --verbose) show_verbose=true; shift ;;
+            *)
+                if [ -z "$prd_file" ]; then
+                    prd_file="$1"
+                fi
+                shift
+                ;;
+        esac
+    done
+
+    if [ -z "$prd_file" ]; then
+        echo -e "${RED}Usage: loki plan <PRD file>${NC}"
+        echo "Run 'loki plan --help' for usage."
+        return 1
+    fi
+
+    if [ ! -f "$prd_file" ]; then
+        echo -e "${RED}PRD file not found: $prd_file${NC}"
+        return 1
+    fi
+
+    local prd_path
+    prd_path="$(cd "$(dirname "$prd_file")" && pwd)/$(basename "$prd_file")"
+
+    show_prd_plan "$prd_path" "$show_json" "$show_verbose"
+}
+
+# Helper: decide whether to auto-show the plan from a major command.
+# v6.81.1: default ON, opt-out via --no-plan. Also auto-skipped when stdout is
+# not a TTY and --no-plan was not explicitly set (CI/automation contexts),
+# logging a one-line "plan skipped: non-interactive" to stderr for visibility.
+maybe_show_auto_plan() {
+    local prd_path="$1"
+    local no_plan_flag="${2:-false}"  # user passed --no-plan explicitly
+
+    # Explicit opt-out wins.
+    if [[ "$no_plan_flag" == "true" ]]; then
+        return 0
+    fi
+
+    # PRD missing: silently skip (other commands will emit their own errors).
+    if [ -z "$prd_path" ] || [ ! -f "$prd_path" ]; then
+        return 0
+    fi
+
+    # Non-TTY heuristic: keep CI / pipe output clean. Log to stderr so it is
+    # still surfaced in logs without corrupting stdout parsers.
+    if [ ! -t 1 ]; then
+        echo "plan skipped: non-interactive (pass --no-plan to silence, or run 'loki plan <PRD>' explicitly)" >&2
+        return 0
+    fi
+
+    local abs_prd
+    abs_prd="$(cd "$(dirname "$prd_path")" && pwd)/$(basename "$prd_path")"
+    show_prd_plan "$abs_prd" "false" "false"
+}
+
 # Main command dispatcher
 main() {
     if [ $# -eq 0 ]; then

package/autonomy/run.sh

@@ -3763,9 +3763,12 @@ track_iteration_complete() {
     [ -z "$phase" ] && phase=$(python3 -c "import json; print(json.load(open('.loki/state/orchestrator.json')).get('currentPhase', 'unknown'))" 2>/dev/null || echo "unknown")
 
     # Read token data from context tracker output (v5.42.0)
+    # v6.82.0: also capture cache_read_tokens / cache_creation_tokens for
+    # prompt-cache hit-rate analysis (S1.1 prompt restructure).
     local iter_input=0 iter_output=0 iter_cost=0
+    local iter_cache_read=0 iter_cache_creation=0
     if [ -f ".loki/context/tracking.json" ]; then
-        read iter_input iter_output iter_cost < <(python3 -c "
+        read iter_input iter_output iter_cost iter_cache_read iter_cache_creation < <(python3 -c "
 import json
 try:
     t = json.load(open('.loki/context/tracking.json'))
@@ -3773,11 +3776,17 @@ try:
     match = [i for i in iters if i.get('iteration') == $iteration]
     if match:
         m = match[-1]
-        print(m.get('input_tokens', 0), m.get('output_tokens', 0), m.get('cost_usd', 0))
+        print(
+            m.get('input_tokens', 0),
+            m.get('output_tokens', 0),
+            m.get('cost_usd', 0),
+            m.get('cache_read_tokens', 0),
+            m.get('cache_creation_tokens', 0),
+        )
     else:
-        print(0, 0, 0)
-except: print(0, 0, 0)
-" 2>/dev/null || echo "0 0 0")
+        print(0, 0, 0, 0, 0)
+except: print(0, 0, 0, 0, 0)
+" 2>/dev/null || echo "0 0 0 0 0")
     fi
 
     cat > ".loki/metrics/efficiency/iteration-${iteration}.json" << EFF_EOF
@@ -3790,6 +3799,8 @@ except: print(0, 0, 0)
   "status": "$status_str",
   "input_tokens": ${iter_input:-0},
   "output_tokens": ${iter_output:-0},
+  "cache_read_tokens": ${iter_cache_read:-0},
+  "cache_creation_tokens": ${iter_cache_creation:-0},
   "cost_usd": ${iter_cost:-0},
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 }
@@ -7596,18 +7607,87 @@ except Exception:
     return 0
 }
 
-# Check if completion promise is fulfilled in log output
+# Check if the loki_complete_task MCP tool was invoked in this iteration.
+# The tool writes a payload to .loki/signals/TASK_COMPLETION_CLAIMED with the
+# structured completion claim. When the signal exists, we read it, log the
+# structured event, and consume (remove) the file. Returns 0 on detection.
+#
+# Output on stdout: the JSON payload (for callers that want to log it).
+check_task_completion_signal() {
+    local signal_file=".loki/signals/TASK_COMPLETION_CLAIMED"
+    if [ ! -f "$signal_file" ]; then
+        return 1
+    fi
+
+    local payload
+    payload=$(cat "$signal_file" 2>/dev/null || echo "")
+    if [ -z "$payload" ]; then
+        # Empty signal -- treat as noise and clean up
+        rm -f "$signal_file" 2>/dev/null
+        return 1
+    fi
+
+    # Emit a structured event for observability (best-effort).
+    local statement evidence confidence
+    statement=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    print(d.get('statement',''))
+except Exception:
+    pass
+" <<< "$payload" 2>/dev/null || echo "")
+    evidence=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    print(d.get('evidence',''))
+except Exception:
+    pass
+" <<< "$payload" 2>/dev/null || echo "")
+    confidence=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    print(d.get('confidence','medium'))
+except Exception:
+    print('medium')
+" <<< "$payload" 2>/dev/null || echo "medium")
+
+    emit_event_json "task_completion_claim" \
+        "statement=${statement:0:500}" \
+        "confidence=${confidence}" \
+        "evidence_length=${#evidence}"
+
+    # Return the payload on stdout
+    printf '%s\n' "$payload"
+
+    # Consume the signal (next iteration would otherwise re-trigger)
+    rm -f "$signal_file" 2>/dev/null
+    return 0
+}
+
+# Check if completion promise is fulfilled in log output.
+#
+# As of v6.82.0, the default path is the MCP tool `loki_complete_task`
+# (detected via check_task_completion_signal above). The legacy grep-based
+# detection is retained behind LOKI_LEGACY_COMPLETION_MATCH=true for rollback.
 check_completion_promise() {
     local log_file="$1"
 
-    # Check for the completion promise phrase in recent log output
-    if grep -q "COMPLETION PROMISE FULFILLED" "$log_file" 2>/dev/null; then
+    # New default: structured signal from the loki_complete_task MCP tool.
+    if check_task_completion_signal >/dev/null 2>&1; then
         return 0
     fi
 
-    # Check for custom completion promise text
-    if [ -n "$COMPLETION_PROMISE" ] && grep -qF "$COMPLETION_PROMISE" "$log_file" 2>/dev/null; then
-        return 0
+    # Legacy grep fallback (opt-in via env flag for rollback).
+    if [ "${LOKI_LEGACY_COMPLETION_MATCH:-false}" = "true" ]; then
+        if grep -q "COMPLETION PROMISE FULFILLED" "$log_file" 2>/dev/null; then
+            return 0
+        fi
+        if [ -n "$COMPLETION_PROMISE" ] && grep -qF "$COMPLETION_PROMISE" "$log_file" 2>/dev/null; then
+            return 0
+        fi
     fi
 
     return 1
@@ -8360,12 +8440,16 @@ build_prompt() {
     # Ralph Wiggum Mode - Reason-Act-Reflect-VERIFY cycle with self-verification loop (Boris Cherny pattern)
     local rarv_instruction="RALPH WIGGUM MODE ACTIVE. Use Reason-Act-Reflect-VERIFY cycle: 1) REASON - READ .loki/CONTINUITY.md including 'Mistakes & Learnings' section to avoid past errors. CHECK .loki/state/relevant-learnings.json for cross-project learnings from previous projects (mistakes to avoid, patterns to apply). Check .loki/state/ and .loki/queue/, identify next task. CHECK .loki/state/resources.json for system resource warnings - if CPU or memory is high, reduce parallel agent spawning or pause non-critical tasks. Limit to MAX_PARALLEL_AGENTS=${MAX_PARALLEL_AGENTS}. If queue empty, find new improvements. 2) ACT - Execute task, write code, commit changes atomically (git checkpoint). 3) REFLECT - Update .loki/CONTINUITY.md with progress, update state, identify NEXT improvement. Save valuable learnings for future projects. 4) VERIFY - Run automated tests (unit, integration, E2E), check compilation/build, verify against spec. IF VERIFICATION FAILS: a) Capture error details (stack trace, logs), b) Analyze root cause, c) UPDATE 'Mistakes & Learnings' in CONTINUITY.md with what failed, why, and how to prevent, d) Rollback to last good git checkpoint if needed, e) Apply learning and RETRY from REASON. If verification passes, mark task complete and continue. This self-verification loop achieves 2-3x quality improvement. CRITICAL: There is NEVER a 'finished' state - always find the next improvement, optimization, test, or feature."
 
-    # Completion promise instruction (only if set)
+    # Completion instruction (S0.2 -- structured tool call).
+    # When PRD requirements are implemented, tests pass, and the checklist is
+    # at or near 100%, the agent MUST invoke the `loki_complete_task` MCP tool
+    # (defined in mcp/server.py) with completion_statement + evidence fields,
+    # instead of emitting a prose completion string.
     local completion_instruction=""
     if [ -n "$COMPLETION_PROMISE" ]; then
-        completion_instruction="COMPLETION_PROMISE: [$COMPLETION_PROMISE]. ONLY output 'COMPLETION PROMISE FULFILLED: $COMPLETION_PROMISE' when this EXACT condition is met."
+        completion_instruction="COMPLETION_PROMISE: [$COMPLETION_PROMISE]. When all PRD requirements are implemented, tests pass, and the PRD checklist is at or near 100%, invoke the loki_complete_task MCP tool with your completion_statement and evidence (cite tests that passed, checklist items verified, files created/modified). Do NOT emit a completion string in prose -- use the tool call."
     else
-        completion_instruction="NO COMPLETION PROMISE SET. Continue finding improvements. The Completion Council will evaluate your progress periodically. Iteration $iteration of max $MAX_ITERATIONS."
+        completion_instruction="NO COMPLETION PROMISE SET. Continue finding improvements. The Completion Council will evaluate your progress periodically. Iteration $iteration of max $MAX_ITERATIONS. If you do decide the task is complete, invoke the loki_complete_task MCP tool with a structured statement and evidence rather than emitting prose."
     fi
 
     # Core autonomous instructions - NO questions, NO waiting, NEVER say done
@@ -8373,7 +8457,7 @@ build_prompt() {
     if [ "$AUTONOMY_MODE" = "perpetual" ] || [ "$PERPETUAL_MODE" = "true" ]; then
         autonomous_suffix="CRITICAL AUTONOMY RULES: 1) NEVER ask questions - just decide. 2) NEVER wait for confirmation - just act. 3) NEVER say 'done' or 'complete' - there's always more to improve. 4) NEVER stop voluntarily - if out of tasks, create new ones (add tests, optimize, refactor, add features). 5) Work continues PERPETUALLY. Even if PRD is implemented, find bugs, add tests, improve UX, optimize performance."
     else
-        autonomous_suffix="CRITICAL AUTONOMY RULES: 1) NEVER ask questions - just decide. 2) NEVER wait for confirmation - just act. 3) When all PRD requirements are implemented and tests pass, output the completion promise text EXACTLY: '$COMPLETION_PROMISE'. 4) If out of tasks but PRD is not fully implemented, continue working on remaining requirements. 5) Focus on completing PRD scope, not endless improvements."
+        autonomous_suffix="CRITICAL AUTONOMY RULES: 1) NEVER ask questions - just decide. 2) NEVER wait for confirmation - just act. 3) When all PRD requirements are implemented and tests pass, invoke the loki_complete_task MCP tool (completion_statement='$COMPLETION_PROMISE' plus evidence + confidence). Do not emit completion prose. 4) If out of tasks but PRD is not fully implemented, continue working on remaining requirements. 5) Focus on completing PRD scope, not endless improvements."
     fi
 
     # Skill files are always copied to .loki/skills/ for all providers
@@ -8655,42 +8739,154 @@ except Exception:
         fi
     fi
 
-    # Degraded providers with small models need simplified prompts
-    # Full RARV/SDLC instructions overwhelm models < 30B parameters
+    # S1.1 -- Static-first prompt assembly with cache-breakpoint marker.
+    #
+    # The prior shape (v<=6.81.x) concatenated ~13 dynamic blobs BEFORE the
+    # 4-5 static instruction blobs, which destroyed Claude's prefix cache on
+    # every iteration. The new layout places the stable instruction set first
+    # (prd_anchor + RARV/SDLC/autonomy/memory instructions), emits a literal
+    # [CACHE_BREAKPOINT] marker, then appends the volatile per-iteration
+    # context inside a <dynamic_context> tag.
+    #
+    # The [CACHE_BREAKPOINT] marker is a documentation anchor today. When the
+    # Claude CLI migration exposes cache_control, the orchestrator can split
+    # the prompt at this marker and set cache_control on the prefix half.
+    #
+    # Rollback: set LOKI_LEGACY_PROMPT_ORDERING=true to restore the previous
+    # dynamic-first concatenation order.
+
+    if [ "${LOKI_LEGACY_PROMPT_ORDERING:-false}" = "true" ]; then
+        # Legacy dynamic-first ordering (pre-v6.82.0). Retained for rollback.
+        if [ "${PROVIDER_DEGRADED:-false}" = "true" ]; then
+            local _legacy_prd_content=""
+            if [ -n "$prd" ] && [ -f "$prd" ]; then
+                _legacy_prd_content=$(head -c 4000 "$prd")
+            fi
+            if [ $retry -eq 0 ]; then
+                if [ -n "$prd" ]; then
+                    echo "You are a coding assistant. Read and implement the requirements from the PRD below. Write working code, run tests if possible, and commit changes. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks} PRD contents: $_legacy_prd_content"
+                else
+                    echo "You are a coding assistant. Analyze this codebase and suggest improvements. Write working code and commit changes. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks}"
+                fi
+            else
+                if [ -n "$prd" ]; then
+                    echo "You are a coding assistant. Continue working on iteration $iteration. Review what exists, implement remaining PRD requirements, fix any issues, add tests. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks} PRD contents: $_legacy_prd_content"
+                else
+                    echo "You are a coding assistant. Continue working on iteration $iteration. Review what exists, improve code, fix bugs, add tests. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks}"
+                fi
+            fi
+        else
+            if [ $retry -eq 0 ]; then
+                if [ -n "$prd" ]; then
+                    echo "Loki Mode with PRD at $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
+                else
+                    echo "Loki Mode. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
+                fi
+            else
+                if [ -n "$prd" ]; then
+                    echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
+                else
+                    echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
+                fi
+            fi
+        fi
+        return 0
+    fi
+
+    # --- New static-first layout (v6.82.0+) ---
+    #
+    # assemble_prompt_static outputs the cache-stable prefix:
+    #   <loki_system>
+    #   {prd_anchor}
+    #   {rarv_instruction + sdlc_instruction + autonomous_suffix + memory_instruction}
+    #   </loki_system>
+    #   [CACHE_BREAKPOINT]
+    #
+    # assemble_prompt_dynamic outputs the volatile tail wrapped in
+    # <dynamic_context iteration=".." retry=".."> ... </dynamic_context>.
+    #
+    # Keeping these as inline local helpers (nested functions via eval are
+    # awkward in bash) -- we emit them as two contiguous printf blocks so the
+    # logic is self-documenting and byte-reproducible.
+
     if [ "${PROVIDER_DEGRADED:-false}" = "true" ]; then
+        # Degraded providers: simpler wording, but still static-first.
         local prd_content=""
         if [ -n "$prd" ] && [ -f "$prd" ]; then
             prd_content=$(head -c 4000 "$prd")
         fi
 
-        if [ $retry -eq 0 ]; then
-            if [ -n "$prd" ]; then
-                echo "You are a coding assistant. Read and implement the requirements from the PRD below. Write working code, run tests if possible, and commit changes. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks} PRD contents: $prd_content"
-            else
-                echo "You are a coding assistant. Analyze this codebase and suggest improvements. Write working code and commit changes. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks}"
-            fi
+        local degraded_prd_anchor="Loki Mode"
+        [ -n "$prd" ] && degraded_prd_anchor="Loki Mode with PRD"
+
+        # STATIC PREFIX (cache-stable across iterations)
+        printf '<loki_system>\n'
+        printf '%s\n' "$degraded_prd_anchor"
+        if [ -n "$prd" ]; then
+            printf 'You are a coding assistant. Read and implement the requirements from the PRD. Write working code, run tests if possible, and commit changes.\n'
         else
-            if [ -n "$prd" ]; then
-                echo "You are a coding assistant. Continue working on iteration $iteration. Review what exists, implement remaining PRD requirements, fix any issues, add tests. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks} PRD contents: $prd_content"
-            else
-                echo "You are a coding assistant. Continue working on iteration $iteration. Review what exists, improve code, fix bugs, add tests. ${human_directive:+Priority: $human_directive} ${queue_tasks:+Tasks: $queue_tasks}"
-            fi
+            printf 'You are a coding assistant. Analyze this codebase and suggest improvements. Write working code and commit changes.\n'
+        fi
+        printf '</loki_system>\n'
+        printf '[CACHE_BREAKPOINT]\n'
+
+        # DYNAMIC TAIL (changes every iteration)
+        printf '<dynamic_context iteration="%s" retry="%s">\n' "$iteration" "$retry"
+        [ -n "$human_directive" ] && printf 'Priority: %s\n' "$human_directive"
+        [ -n "$queue_tasks" ] && printf 'Tasks: %s\n' "$queue_tasks"
+        if [ -n "$prd" ]; then
+            printf 'PRD contents: %s\n' "$prd_content"
         fi
+        printf '</dynamic_context>\n'
+        return 0
+    fi
+
+    # Full-featured providers (Claude, etc.)
+    local prd_anchor
+    if [ -n "$prd" ]; then
+        prd_anchor="Loki Mode with PRD at $prd"
     else
-        if [ $retry -eq 0 ]; then
-            if [ -n "$prd" ]; then
-                echo "Loki Mode with PRD at $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
-            else
-                echo "Loki Mode. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
-            fi
+        prd_anchor="Loki Mode"
+    fi
+
+    # STATIC PREFIX (cache-stable across iterations).
+    # Order is deterministic so the prefix is byte-identical for iter N and N+1.
+    printf '<loki_system>\n'
+    printf '%s\n' "$prd_anchor"
+    printf '%s\n' "$rarv_instruction"
+    printf '%s\n' "$sdlc_instruction"
+    printf '%s\n' "$autonomous_suffix"
+    printf '%s\n' "$memory_instruction"
+    # For codebase-analysis mode (no PRD), analysis_instruction is part of the
+    # static prefix so it remains cache-stable.
+    if [ -z "$prd" ]; then
+        printf '%s\n' "$analysis_instruction"
+    fi
+    printf '</loki_system>\n'
+    printf '[CACHE_BREAKPOINT]\n'
+
+    # DYNAMIC TAIL -- all per-iteration context goes here.
+    printf '<dynamic_context iteration="%s" retry="%s">\n' "$iteration" "$retry"
+    if [ $retry -gt 0 ]; then
+        if [ -n "$prd" ]; then
+            printf 'Resume iteration #%s (retry #%s). PRD: %s\n' "$iteration" "$retry" "$prd"
         else
-            if [ -n "$prd" ]; then
-                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
-            else
-                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $completion_instruction $sdlc_instruction $autonomous_suffix"
-            fi
+            printf 'Resume iteration #%s (retry #%s). Use .loki/generated-prd.md if exists.\n' "$iteration" "$retry"
         fi
     fi
+    [ -n "$human_directive" ] && printf '%s\n' "$human_directive"
+    [ -n "$gate_failure_context" ] && printf '%s\n' "$gate_failure_context"
+    [ -n "$queue_tasks" ] && printf '%s\n' "$queue_tasks"
+    [ -n "$bmad_context" ] && printf '%s\n' "$bmad_context"
+    [ -n "$openspec_context" ] && printf '%s\n' "$openspec_context"
+    [ -n "$mirofish_context" ] && printf '%s\n' "$mirofish_context"
+    [ -n "$magic_context" ] && printf '%s\n' "$magic_context"
+    [ -n "$checklist_status" ] && printf '%s\n' "$checklist_status"
+    [ -n "$app_runner_info" ] && printf '%s\n' "$app_runner_info"
+    [ -n "$playwright_info" ] && printf '%s\n' "$playwright_info"
+    [ -n "$memory_context_section" ] && printf '%s\n' "$memory_context_section"
+    printf '%s\n' "$completion_instruction"
+    printf '</dynamic_context>\n'
 }
 
 #===============================================================================
@@ -10317,12 +10513,21 @@ if __name__ == "__main__":
                 return 0
             fi
 
-            # Only stop if EXPLICIT completion promise text was output
-            # BUG-RUN-001: Use per-iteration output, not stale daily log
-            if [ -n "$COMPLETION_PROMISE" ] && check_completion_promise "$iter_output"; then
+            # Stop if either:
+            #   (a) the agent invoked the loki_complete_task MCP tool
+            #       (detected via .loki/signals/TASK_COMPLETION_CLAIMED), OR
+            #   (b) LOKI_LEGACY_COMPLETION_MATCH=true AND the completion
+            #       promise text appears in the iteration output.
+            # The check_completion_promise() helper encapsulates both.
+            # BUG-RUN-001: Use per-iteration output, not stale daily log.
+            if check_completion_promise "$iter_output"; then
                 echo ""
-                log_header "COMPLETION PROMISE FULFILLED: $COMPLETION_PROMISE"
-                log_info "Explicit completion promise detected in output."
+                if [ -n "$COMPLETION_PROMISE" ]; then
+                    log_header "COMPLETION PROMISE FULFILLED: $COMPLETION_PROMISE"
+                else
+                    log_header "TASK COMPLETION CLAIMED (via loki_complete_task)"
+                fi
+                log_info "Explicit completion signal detected."
                 # Run memory consolidation on successful completion
                 log_info "Running memory consolidation..."
                 run_memory_consolidation

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.81.0"
+__version__ = "6.82.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/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.81.0
+**Version:** v6.82.0
 
 ---
 

package/mcp/__init__.py

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

package/mcp/server.py

@@ -1005,6 +1005,111 @@ async def loki_consolidate_memory(since_hours: int = 24) -> str:
         return json.dumps({"error": str(e)})
 
 
+@mcp.tool()
+async def loki_complete_task(
+    completion_statement: str,
+    evidence: str,
+    confidence: str = "medium",
+) -> str:
+    """
+    Declare that the current PRD / task is complete.
+
+    Replaces the legacy 'COMPLETION PROMISE FULFILLED: ...' prose string with a
+    structured tool call. The orchestrator (run.sh) detects this via a signal
+    file and stops the iteration loop gracefully.
+
+    Args:
+        completion_statement: A short statement of what is complete (for example,
+            "PRD requirements implemented, all tests passing, checklist 100%").
+        evidence: Concrete evidence supporting the claim -- tests that passed,
+            checklist items verified, files created/modified, metrics hit.
+        confidence: One of 'high', 'medium', 'low' (default 'medium').
+            'low' signals the orchestrator should still run the completion council.
+
+    Returns:
+        JSON: {"recorded": true, "path": ".loki/events.jsonl"} on success,
+        {"error": "..."} otherwise.
+    """
+    _emit_tool_event_async(
+        'loki_complete_task', 'start',
+        parameters={
+            'confidence': confidence,
+            'statement_len': len(completion_statement or ''),
+            'evidence_len': len(evidence or ''),
+        },
+    )
+
+    # Validate inputs
+    if not completion_statement or not completion_statement.strip():
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error='completion_statement required')
+        return json.dumps({"error": "completion_statement is required"})
+    if not evidence or not evidence.strip():
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error='evidence required')
+        return json.dumps({"error": "evidence is required"})
+
+    confidence_norm = (confidence or 'medium').strip().lower()
+    if confidence_norm not in ('high', 'medium', 'low'):
+        confidence_norm = 'medium'
+
+    timestamp = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
+
+    payload = {
+        'type': 'task_completion_claim',
+        'statement': completion_statement.strip(),
+        'evidence': evidence.strip(),
+        'confidence': confidence_norm,
+        'timestamp': timestamp,
+    }
+
+    # Wrap event record with timestamp and type at the outer level so it matches
+    # the shape of other events in .loki/events.jsonl.
+    event_record = {
+        'timestamp': timestamp,
+        'type': 'task_completion_claim',
+        'data': payload,
+    }
+
+    try:
+        # Ensure .loki/ and .loki/signals/ exist under the project root
+        loki_dir = safe_path_join('.loki')
+        os.makedirs(loki_dir, exist_ok=True)
+        signals_dir = safe_path_join('.loki', 'signals')
+        os.makedirs(signals_dir, exist_ok=True)
+
+        events_path = safe_path_join('.loki', 'events.jsonl')
+        with safe_open(events_path, 'a') as f:
+            f.write(json.dumps(event_record) + '\n')
+
+        signal_path = safe_path_join('.loki', 'signals', 'TASK_COMPLETION_CLAIMED')
+        with safe_open(signal_path, 'w') as f:
+            f.write(json.dumps(payload, indent=2))
+
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete', result_status='success')
+        return json.dumps({
+            "recorded": True,
+            "path": ".loki/events.jsonl",
+            "signal": ".loki/signals/TASK_COMPLETION_CLAIMED",
+            "confidence": confidence_norm,
+        })
+    except PathTraversalError as e:
+        logger.error(f"Path traversal attempt blocked in loki_complete_task: {e}")
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error='Access denied')
+        return json.dumps({"error": "Access denied"})
+    except Exception as e:
+        logger.error(f"loki_complete_task failed: {e}")
+        _emit_tool_event_async(
+            'loki_complete_task', 'complete',
+            result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
 # ============================================================
 # RESOURCES - Data that can be read
 # ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.81.0",
+  "version": "6.82.0",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",