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

package/VERSION

@@ -1 +1 @@
-9.56.0
+9.59.0

package/autonomy/completion-council.sh

@@ -72,6 +72,38 @@ for _cc_cand in "$_LOKI_CC_DIR/lib/secret-scan.sh" "${SCRIPT_DIR:-}/lib/secret-s
 done
 unset _LOKI_CC_DIR _cc_cand
 
+# BACKLOG 134: the three test-result readers (council_heuristic_review,
+# council_evaluate_member, council_devils_advocate_review) resolve their
+# interpreter through run.sh's _loki_snapshot_py_tool and run it -I -S: -E alone
+# still loads user site-packages, whose .pth "import" lines run before any
+# sys.path scrub and can forge json.load (see that function's comment in
+# run.sh for the full rationale and accepted gaps). run.sh sources this file
+# BEFORE it defines _loki_snapshot_py_tool, so in production run.sh's own
+# definition replaces this one; the copy below only serves callers that source
+# this file on its own (tests). run.sh is the source of truth: keep this copy
+# byte-identical to it.
+declare -F _loki_snapshot_py_tool >/dev/null 2>&1 || \
+_loki_snapshot_py_tool() {
+    local c
+    for c in /usr/bin/python3 /bin/python3; do
+        [ -x "$c" ] && [ ! -d "$c" ] && "$c" -I -S -c '' >/dev/null 2>&1 && { printf '%s\n' "$c"; return 0; }
+    done
+    local dir
+    local IFS=:
+    for dir in $PATH; do
+        case "$dir" in
+            /*) ;;
+            *) continue ;;
+        esac
+        if [ -x "$dir/python3" ] && [ ! -d "$dir/python3" ] \
+           && "$dir/python3" -I -S -c '' >/dev/null 2>&1; then
+            printf '%s\n' "$dir/python3"
+            return 0
+        fi
+    done
+    return 1
+}
+
 # Council configuration
 COUNCIL_ENABLED=${LOKI_COUNCIL_ENABLED:-true}
 COUNCIL_SIZE=${LOKI_COUNCIL_SIZE:-3}
@@ -3484,8 +3516,10 @@ council_heuristic_review() {
             # evidence -> REJECT (keep iterating), never a heuristic APPROVE.
             local _tr_file=".loki/quality/test-results.json"
             local _tests_ok=0
-            if [ -f "$_tr_file" ] && command -v python3 >/dev/null 2>&1; then
-                _tests_ok=$(_TR="$_tr_file" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
+            local _tr_py=""
+            [ -f "$_tr_file" ] && _tr_py="$(_loki_snapshot_py_tool)" || _tr_py=""
+            if [ -n "$_tr_py" ]; then
+                _tests_ok=$(_TR="$_tr_file" "$_tr_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
 import json, os
 try:
     with open(os.environ['_TR']) as f:
@@ -3668,9 +3702,11 @@ council_evaluate_member() {
     local tr_file="$loki_dir/quality/test-results.json"
     local test_evidence="absent"   # absent | pass | fail | inconclusive
     local test_runner_seen="none"
-    if [ -f "$tr_file" ]; then
+    local _tr_py=""
+    [ -f "$tr_file" ] && _tr_py="$(_loki_snapshot_py_tool)" || _tr_py=""
+    if [ -n "$_tr_py" ]; then
         local _tr_status
-        _tr_status=$(_TR_FILE="$tr_file" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
+        _tr_status=$(_TR_FILE="$tr_file" "$_tr_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
 import json, os, sys
 try:
     with open(os.environ['_TR_FILE']) as f:
@@ -3727,14 +3763,25 @@ else:
             # Cases 6 and 7, with Case 8 as the positive control proving this
             # can still reach COMPLETE when every queue really is empty.
             local unfinished=0
-            local _q _qcount
+            local _q _qcount _q_py=""
             for _q in pending in-progress blocked; do
                 [ -f "$loki_dir/queue/${_q}.json" ] || continue
-                _qcount=$(_QUEUE_FILE="$loki_dir/queue/${_q}.json" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]; import json, os
+                # Same -I -S interpreter as the test-result readers: a user-site
+                # .pth must not be able to make this count read 0.
+                [ -n "$_q_py" ] || _q_py="$(_loki_snapshot_py_tool)" || _q_py=""
+                _qcount=""
+                [ -n "$_q_py" ] && _qcount=$(_QUEUE_FILE="$loki_dir/queue/${_q}.json" "$_q_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]; import json, os
 d = json.load(open(os.environ['_QUEUE_FILE']))
-print(len(d.get('tasks', d) if isinstance(d, dict) else d))" 2>/dev/null || echo "0")
-                # Guard against a non-numeric read (malformed file, python absent).
-                case "$_qcount" in ''|*[!0-9]*) _qcount=0 ;; esac
+print(len(d.get('tasks', d) if isinstance(d, dict) else d))" 2>/dev/null)
+                # Fail closed: a present queue file whose count cannot be read
+                # (malformed file, no interpreter) is not evidence it is empty.
+                case "$_qcount" in
+                    ''|*[!0-9]*)
+                        blocked="true"
+                        reasons="${reasons}${_q} queue count unreadable; "
+                        continue
+                        ;;
+                esac
                 if [ "$_qcount" -gt 0 ]; then
                     unfinished=$((unfinished + _qcount))
                     blocked="true"
@@ -3969,9 +4016,11 @@ council_devils_advocate_review() {
     # (nothing writes .loki/logs/test-*.log, so an empty glob is the normal case
     # and must never veto a unanimous COMPLETE on its own).
     local tr_file="$loki_dir/quality/test-results.json"
-    if [ -f "$tr_file" ]; then
+    local _tr_py=""
+    [ -f "$tr_file" ] && _tr_py="$(_loki_snapshot_py_tool)" || _tr_py=""
+    if [ -n "$_tr_py" ]; then
         local _tr_status
-        _tr_status=$(_TR_FILE="$tr_file" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
+        _tr_status=$(_TR_FILE="$tr_file" "$_tr_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
 import json, os, sys
 try:
     with open(os.environ['_TR_FILE']) as f:
@@ -3994,6 +4043,8 @@ else:
             ((issues_found++))
             issue_details="${issue_details}structured test results red (pass==false); "
         fi
+    elif [ -f "$tr_file" ]; then
+        ((issues_found++)); issue_details="${issue_details}test results unreadable (no isolated python3); "
     fi
     # Additional source: any legacy test log that shows no pass indicator is a red
     # signal. Missing logs are NOT counted (this path is not written by the runner).
@@ -4009,8 +4060,18 @@ else:
     # Skeptical check 2: Are there still failing tasks in the queue?
     if [ -f "$loki_dir/queue/failed.json" ]; then
         local failed_count
-        failed_count=$(_QUEUE_FILE="$loki_dir/queue/failed.json" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]; import json, os; print(len(json.load(open(os.environ['_QUEUE_FILE']))))" 2>/dev/null || echo "0")
-        if [ "$failed_count" -gt 0 ]; then
+        local failed_count="" _fq_py=""
+        _fq_py="$(_loki_snapshot_py_tool)" || _fq_py=""
+        [ -n "$_fq_py" ] && failed_count=$(_QUEUE_FILE="$loki_dir/queue/failed.json" "$_fq_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]; import json, os; print(len(json.load(open(os.environ['_QUEUE_FILE']))))" 2>/dev/null)
+        # Fail closed: an unreadable failed-queue count (malformed, no
+        # interpreter) vetoes instead of reading as zero.
+        case "$failed_count" in
+            ''|*[!0-9]*)
+                ((issues_found++))
+                issue_details="${issue_details}failed queue count unreadable; "
+                ;;
+        esac
+        if [ "${failed_count:-0}" -gt 0 ] 2>/dev/null; then
             ((issues_found++))
             issue_details="${issue_details}$failed_count tasks in failed queue; "
         fi
@@ -4492,8 +4553,11 @@ _council_convergence_evidence_green() {
     # Affirmative test-green is REQUIRED: a real runner that passed. A missing
     # file or runner=="none" (no suite) is NOT affirmative evidence -> not green.
     [ -f "$tr_file" ] || return 1
+    # -I -S interpreter (see _loki_snapshot_py_tool); none resolvable -> not green.
+    local _cv_py
+    _cv_py="$(_loki_snapshot_py_tool)" || return 1
     local tr_state
-    tr_state=$(_TR_FILE="$tr_file" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
+    tr_state=$(_TR_FILE="$tr_file" "$_cv_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
 import json, os, sys
 try:
     with open(os.environ['_TR_FILE']) as f:
@@ -4516,7 +4580,7 @@ print('yes' if (runner != 'none' and passed is True
     local results_file="${TARGET_DIR:-.}/.loki/checklist/verification-results.json"
     if [ -f "$results_file" ]; then
         local cl_state
-        cl_state=$(_RESULTS_FILE="$results_file" python3 -E -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
+        cl_state=$(_RESULTS_FILE="$results_file" "$_cv_py" -I -S -c "import sys; sys.path[:] = [p for p in sys.path if p not in ('', '.')]
 import json, os, sys
 try:
     with open(os.environ['_RESULTS_FILE']) as f:

package/autonomy/loki

@@ -33945,8 +33945,10 @@ except Exception:
         # Only scan added lines (starting with "+") to avoid flagging deleted code
         while IFS= read -r match; do
             [ -z "$match" ] && continue
-            local ml
-            ml=$(echo "$match" | cut -d: -f1)
+            # grep -n emits "N:content"; take the number before the first
+            # colon without forking echo+cut per line (matters at finding
+            # counts in the thousands+).
+            local ml="${match%%:*}"
             _ci_add_finding "diff" "$ml" "$sev" "$cat" "$finding" "$suggestion"
         done < <(printf '%s\n' "$diff_content" \
             | grep -n '^+' \
@@ -34089,8 +34091,11 @@ TEST_SUGGEST_PY
     # --- Tally findings ---
     local count_critical=0 count_high=0 count_medium=0 count_low=0 count_info=0
     for f in "${findings[@]+"${findings[@]}"}"; do
-        local sev
-        sev=$(echo "$f" | cut -d'|' -f3)
+        # "file|line|sev|cat|finding|suggestion" (see _ci_add_finding above).
+        # No echo+cut fork per finding -- this loop runs once per finding and
+        # dominated the runtime at the fixture's old ARG_MAX-scale sizes.
+        local sev _tally_file _tally_line _tally_cat _tally_finding _tally_suggestion
+        IFS='|' read -r _tally_file _tally_line sev _tally_cat _tally_finding _tally_suggestion <<< "$f"
         case "$sev" in
             CRITICAL) count_critical=$((count_critical + 1)) ;;
             HIGH) count_high=$((count_high + 1)) ;;

package/autonomy/run.sh

@@ -9218,10 +9218,27 @@ setup_agent_branch() {
 
     # Record the user's own untracked and gitignored files so
     # commit_session_changes and the receipt leave them alone.
-    local snap_ok=1 leftover=""
+    local snap_ok=1 leftover="" gittool=""
     if ! _loki_snapshot_or_fail_closed; then
         snap_ok=0
-        rm -f .loki/state/preexisting-untracked.z .loki/state/preexisting-untracked.sha.z 2>/dev/null
+        rm -f .loki/state/preexisting-untracked.sha.z 2>/dev/null
+        # BACKLOG 88: the receipt (workspace_diff._preexisting_untracked) reads
+        # preexisting-untracked.z on its own, independent of
+        # _LOKI_SNAPSHOT_THIS_RUN below. Leaving it absent after a failed
+        # snapshot (old code: `rm -f` here too) makes the receipt treat EVERY
+        # currently-untracked file as this run's own work, even though nothing
+        # is actually committed -- a pre-existing file the user never touched
+        # gets named as the run's. `ls-files --others --exclude-standard` needs
+        # no --no-renames or --ignored=matching, so it still works on the git
+        # that just failed the richer `status` call above, giving the receipt a
+        # names-only fallback list. Ignored files are not covered by this
+        # fallback (old-git territory), so it is partial, not a full snapshot;
+        # the commit path is untouched (snap_ok stays 0, _LOKI_SNAPSHOT_THIS_RUN
+        # is never set below), so this still fails closed.
+        gittool="$(_loki_snapshot_git_tool)" && \
+            "$gittool" ls-files --others --exclude-standard -z > .loki/state/preexisting-untracked.z.tmp 2>/dev/null && \
+            mv .loki/state/preexisting-untracked.z.tmp .loki/state/preexisting-untracked.z \
+            || rm -f .loki/state/preexisting-untracked.z .loki/state/preexisting-untracked.z.tmp 2>/dev/null
         log_warn "Could not record pre-existing untracked files; this session will commit nothing (review and commit manually)"
     fi
 
@@ -10317,7 +10334,9 @@ _loki_untrack_agent_committed_user_files() {
     fi
     rm -f "$rec.added"
     if [ ! -s "$rec.new" ]; then
-        rm -f "$rec.new"
+        # BACKLOG 102: zero hits this session -- clear a stale record left by
+        # an earlier session, or it persists forever with nothing to read it.
+        rm -f "$rec.new" "$rec"
         return 0
     fi
     mv -f "$rec.new" "$rec"

package/dashboard/__init__.py

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

package/docs/dev/architecture-reference.md

@@ -0,0 +1,99 @@
+# Architecture reference: gates, healing, memory, harness knobs
+
+Moved out of CLAUDE.md (S-78) to keep the root file short. Content unchanged
+except where noted.
+
+## Quality Gates (8 gates; see `skills/quality-gates.md` for the canonical table)
+1. Static analysis (CodeQL, ESLint)
+2. Test suite pass/fail (red blocks; coverage % not measured in this release)
+3. Blind 3-reviewer code review with severity blocking (Critical/High = BLOCK; Medium/Low advisory)
+4. Anti-sycophancy / Devil's Advocate (on unanimous PASS)
+5. Mock-integrity detector (HIGH blocks)
+6. Test-mutation detector (HIGH blocks)
+7. Documentation coverage
+8. Magic Modules debate (ADVISORY by default on both routes; bash enforces only with `LOKI_GATE_MAGIC_DEBATE_BLOCKING=true`, Bun self-skips unless `LOKI_GATE_MAGIC_DEBATE="true"`)
+
+Conditional auditor (not numbered): Backward-compatibility / legacy-healing-auditor (healing mode only - behavioral preservation, v6.67.0).
+
+Note (v10): `docs/v10/DECISIONS.md` D12 refines the review rule above -- unanimous
+APPROVE is still required, and a reproduced blocking finding always vetoes
+regardless of vote count. D13 requires every council/review agent to pin its
+model explicitly rather than inherit the session model.
+
+## Legacy System Healing (introduced v6.67.0)
+- **Current in v7.18.0**: Still active, no breaking changes since v6.67.0. Note: in v7.4.20 the `legacy-healing-auditor` reviewer was gated on healing-mode signals to avoid firing on non-healing changes.
+- **Inspired by**: Amazon AGI Lab's "How Agentic AI Helps Heal Systems We Can't Replace"
+- **CLI**: `loki heal <path> [--phase archaeology|stabilize|isolate|modernize|validate]` (`autonomy/loki:9916`)
+- **Principles**: Friction-as-semantics, failure-first learning, universal adapters, incremental healing, institutional knowledge preservation
+- **Artifacts**: `.loki/healing/` (friction-map.json, failure-modes.json, institutional-knowledge.md)
+- **Review**: `legacy-healing-auditor` specialist added to code review pool (gated)
+- **Gate**: backward-compatibility / legacy-healing auditor (healing mode; not one of the 8 numbered gates) blocks removal of unclassified friction
+- **Hooks**: `hook_pre_healing_modify()` (`autonomy/hooks/migration-hooks.sh:283`), `hook_post_healing_modify()` (`:328`), `hook_healing_phase_gate()` (`:386`)
+- **Memory**: `FrictionPoint` and `FailureMode` schemas for healing-specific memory entries
+- **Skill**: `skills/healing.md` | **Reference**: `references/legacy-healing-patterns.md`
+
+## Memory System (core complete v5.15.0; managed-memory + RAG injector v7.1.0+)
+- **Episodic**: Specific interaction traces (`.loki/memory/episodic/`)
+- **Semantic**: Generalized patterns (`.loki/memory/semantic/`)
+- **Procedural**: Learned skills (`.loki/memory/skills/`)
+- **Progressive Disclosure**: 3-layer loading (index, timeline, full details)
+- **Token Economics**: Discovery vs read token tracking
+- **Vector Search**: Optional embedding-based similarity (sentence-transformers)
+- **Cross-project + RAG injection**: `memory/cross_project.py`, `memory/rag_injector.py`, `memory/knowledge_graph.py` (added v7.x)
+- **Managed memory client**: `memory/managed_memory/` -- gated on `LOKI_MANAGED_MEMORY=true`. See `skills/memory.md`.
+- **CLI**: `loki memory index|timeline|consolidate|economics|retrieve|episode|pattern|skill|vectors`
+- **API**: REST endpoints at `/api/memory/*`
+- **Implementation**: `memory/` Python package (15 modules) with RARV integration
+
+## Metrics System (ToolOrchestra-inspired)
+- **Efficiency**: Task cost tracking (`.loki/metrics/efficiency/`)
+
+## v8 Harness Intelligence (v8.0.0)
+
+Four measured-harness disciplines on the trust core. None can weaken a gate.
+
+- **Prompt-cache discipline**: the prompt splits into a cache-stable
+  `<loki_system>` prefix and a volatile `<dynamic_context>` tail at
+  `[CACHE_BREAKPOINT]`. **Any new always-on instruction MUST go in the prefix**
+  or it busts the cache every iteration.
+  Two accuracy notes, because an earlier version of this bullet overstated it:
+  explicit `cache_control` on that split lives in `sdk_invoker.ts` (the raw-SDK
+  judge path) and is **opt-in, default OFF** behind `LOKI_SDK_PROMPT_CACHE=1`.
+  On the main agent path the Agent SDK's `query()` takes a plain string, so the
+  split is not applied there and the SDK/CLI does its own caching internally.
+  On the bash route the `[CACHE_BREAKPOINT]` marker is a documentation anchor
+  that orders the prompt; it sets no `cache_control` header. The ordering rule
+  above still matters on every route -- a stable prefix is what any cache, ours
+  or the CLI's, can reuse.
+- **Confidence-spike re-check** (`loki-ts/src/runner/council.ts`): delays the
+  done-signal force-stop by ONE iteration when self-reported confidence spikes.
+  Strictly additive (never skips a gate), never delays the stagnation valve,
+  one-shot so a re-spiking run cannot postpone the valve forever.
+  `LOKI_CONFIDENCE_SPIKE=0` / `_DELTA` (40) / `_MIN` (90).
+- **Goal scoring** (`loki-ts/src/runner/goal_score.ts`): flags a
+  `COMPLETION_PROMISE` with no measurable target. Advisory only. Suppressed for
+  an absent goal and in perpetual mode. **Byte-mirrored in `autonomy/run.sh`** --
+  edit BOTH or the `build_prompt` parity fixtures diverge. `LOKI_GOAL_SCORING=0`.
+- **Smart retry** (`loki-ts/src/runner/retry_class.ts`): exits early on a
+  positively-identified permanent failure. **Fail-safe direction is
+  load-bearing**: unrecognized failures stay TRANSIENT and retry as before; rate
+  limits are explicitly excluded from the permanent set. Never invert this
+  default. `LOKI_SMART_RETRY=0`.
+
+Observability: SDK failures emit a structured `capability_degraded` record to
+`.loki/events.jsonl`; `.loki/app-runner/first-preview.json` records
+time-to-first-preview write-once (bash route only).
+
+## Phase 1 / RARV-C Closure Env Vars
+
+Default-on in the Bun runner (see `CHANGELOG.md` v7.x entries; documented in `skills/quality-gates.md:88-110`). Set to `0` to disable; set to `1` to force-enable on the bash route.
+
+- `LOKI_INJECT_FINDINGS` -- inject structured per-finding records into the next-iteration prompt; persists `.loki/state/findings-<iter>.json` after aggregation.
+- `LOKI_OVERRIDE_COUNCIL` -- enable the 3-judge override council on a BLOCK verdict. Requires `LOKI_INJECT_FINDINGS=1` (operator setting only this var alone is a no-op).
+  **The BLOCK-LIFT arm only adjudicates on the Bun route** (`LOKI_SDK_LOOP=1`, or `LOKI_SDK_MODE=full`). A plain `loki start` takes the BASH route (`bin/loki:325`; `LOKI_SDK_MODE` defaults to `off`), where the override lands in a stub that returns `REJECT_OVERRIDE` for every record (`loki-ts/src/commands/internal_phase1.ts:215-227`). Counter-evidence is still parsed and an `override-<iter>.json` transcript is still written, so the feature looks live in the artifacts while never being able to lift a BLOCK.
+  This fail-closed direction is DELIBERATE, not a bug: on the agent-authored route the gated agent writes its own counter-evidence, so mechanical verification is forgeable. On bash the only exits from a Critical/High BLOCK are to fix the finding or to use the human-escape path (`rm .loki/PAUSE`). Documented here because the heading above says "default-on" and, for this one knob's block-lift, that is true only on Bun.
+- `LOKI_AUTO_LEARNINGS` -- auto-write structured learnings per code_review cycle. Optional `LOKI_AUTO_LEARNINGS_EPISODE=1` also writes the learning into the episode store.
+  **Bun route only.** This var has ZERO occurrences in `autonomy/run.sh` and `autonomy/loki` (measured; controls: `LOKI_HANDOFF_MD` returns 2, `LOKI_INJECT_FINDINGS` returns 3), so "set to `1` to force-enable on the bash route" does not apply to this knob -- there is nothing on bash to enable. The bash route DOES have a learnings store (`init_learnings_db`, `run.sh`); what is Bun-only is the automatic per-code_review-cycle write.
+- `LOKI_HANDOFF_MD` -- write a structured handoff doc before iteration close.
+
+These knobs together implement the RARV-C (closure) loop: findings -> override council -> learnings -> handoff. Reference: `skills/quality-gates.md`, `CHANGELOG.md` entries from v7.x for default-on flip and override-council semantics.

package/docs/dev/project-structure.md

@@ -0,0 +1,134 @@
+# Project structure and codebase knowledge graph
+
+Moved out of CLAUDE.md (S-78) to keep the root file short. Content unchanged.
+
+## Project Structure
+
+```
+SKILL.md                    # Slim core skill (~410 lines) - progressive disclosure
+providers/                  # Multi-provider support (5 providers)
+  claude.sh                 # Claude Code - full features (Tier 1)
+  cline.sh                  # Cline - Tier 2
+  codex.sh                  # OpenAI Codex CLI - degraded mode (Tier 3)
+  aider.sh                  # Aider - degraded mode (Tier 3)
+  opencode.sh               # opencode - model-agnostic mode
+  loader.sh                 # Provider loader utility
+  models.sh                 # Model name registry
+memory/                     # Memory system (core v5.15.0; cross-project + RAG injector v7.1.0+; 15 modules)
+  engine.py                 # Core memory engine
+  schemas.py                # Pydantic schemas
+  storage.py                # Storage backend
+  retrieval.py              # Task-aware retrieval
+  consolidation.py          # Episodic-to-semantic pipeline
+  token_economics.py        # Token usage tracking
+  embeddings.py             # Vector embeddings (optional)
+  vector_index.py           # Vector search index
+  layers/                   # Progressive disclosure implementation
+skills/                     # On-demand skill modules (v3.0 architecture)
+  00-index.md               # Module selection rules and routing
+  model-selection.md        # Task tool, parallelization, thinking modes
+  providers.md              # Multi-provider documentation
+  quality-gates.md          # 8-gate system, velocity-quality balance
+  healing.md                # Legacy system healing (Amazon AGI Lab patterns)
+  testing.md                # Playwright, E2E, property-based testing
+  production.md             # HN patterns, CI/CD, context management
+  troubleshooting.md        # Common issues, red flags, fallbacks
+  agents.md                 # 41 agent types, structured prompting
+  artifacts.md              # Generation, code transformation
+  patterns-advanced.md      # OptiMind, k8s-valkey, Constitutional AI
+  parallel-workflows.md     # Git worktrees, parallel streams, auto-merge
+  github-integration.md     # GitHub issue import, PR creation, notifications
+  sdlc-fleet.md              # Six-role standing fleet pattern (see CLAUDE.md)
+references/                 # Detailed documentation (21 files)
+  legacy-healing-patterns.md # Amazon AGI Lab: friction, adapters, archaeology
+  openai-patterns.md        # OpenAI Agents SDK: guardrails, tripwires, handoffs
+  lab-research-patterns.md  # DeepMind + Anthropic: Constitutional AI, debate
+  production-patterns.md    # HN 2025: What actually works in production
+  advanced-patterns.md      # 2025 research patterns (MAR, Iter-VF, GoalAct)
+  tool-orchestration.md     # ToolOrchestra-inspired efficiency & rewards
+  memory-system.md          # Episodic/semantic memory architecture
+  quality-control.md        # Code review, anti-sycophancy, guardrails
+  agent-types.md            # 41 specialized agent definitions
+  sdlc-phases.md            # Full SDLC workflow
+  task-queue.md             # Queue system, circuit breakers
+  core-workflow.md          # RARV cycle, autonomy rules
+  deployment.md             # Cloud deployment instructions
+  business-ops.md           # Business operation workflows
+  mcp-integration.md        # MCP server capabilities
+  competitive-analysis.md   # Auto-Claude, MemOS, Dexter comparison
+  confidence-routing.md     # Model selection by confidence
+  cursor-learnings.md       # Cursor scaling patterns
+  prompt-repetition.md      # Haiku prompt optimization
+  agents.md                 # Agent dispatch patterns
+events/                     # Unified Event Bus (v5.17.0)
+  bus.py                    # Python event bus
+  bus.ts                    # TypeScript event bus
+  emit.sh                   # Bash helper for emitting events
+docs/                       # Architecture documentation
+  SYNERGY-ROADMAP.md        # 5-pillar tool integration architecture
+  v10/                      # v10 program: OPERATING-MODEL.md, DECISIONS.md, BOARD.md, BACKLOG.md, PROGRESS.md
+  dev/                      # Developer reference docs (this file and its siblings)
+autonomy/                   # Runtime and autonomous execution
+  context-tracker.py        # Context window usage tracking
+  notification-checker.py   # Notification trigger evaluation
+templates/                  # 21 PRD templates (saas, cli, discord-bot, etc.)
+benchmarks/                 # SWE-bench and HumanEval benchmarks
+```
+
+## Codebase Knowledge Graph (Quick Reference)
+
+### Top-Level File Map
+
+Line counts approximate; re-run `wc -l` for exact.
+
+| File | Lines | Role |
+|---|---|---|
+| `autonomy/loki` | ~32,700 | CLI (102 cmd_ functions, dispatch at `loki:main`) |
+| `autonomy/run.sh` | ~20,400 | Orchestration engine (RARV loop) |
+| `autonomy/completion-council.sh` | ~3,800 | Completion detection (council voting) |
+| `dashboard/server.py` | ~11,500 | FastAPI (100+ endpoints, WebSocket) |
+| `memory/retrieval.py` | ~2,100 | Task-aware memory retrieval |
+| `memory/storage.py` | ~2,000 | File-based memory backend |
+| `memory/engine.py` | ~1,600 | Memory orchestrator |
+| `memory/consolidation.py` | ~1,100 | Episodic-to-semantic pipeline |
+| `mcp/server.py` | ~2,700 | MCP server (36 tools: 28 in-file + 7 magic + 1 gated managed; +3 resources, 2 prompts) |
+| `providers/loader.sh` | ~185 | Provider loader |
+
+### Key Function Lookup
+
+Verified against v7.5.13 source on 2026-04-29. Line numbers drift; re-verify with `grep -n` before relying on them.
+
+| Function | Location | Purpose |
+|---|---|---|
+| `cmd_start()` | `autonomy/loki` | Start autonomous execution |
+| `main()` (CLI) | `autonomy/loki` | CLI dispatch |
+| `main()` (runner) | `autonomy/run.sh` | Runner entry point |
+| `run_autonomous()` | `autonomy/run.sh` | Main iteration loop |
+| `build_prompt()` | `autonomy/run.sh` | Prompt construction |
+| `save_state()` | `autonomy/run.sh` | Persist state |
+| `council_should_stop()` | `autonomy/completion-council.sh` | Completion decision |
+| `run_code_review()` | `autonomy/run.sh` | 3-reviewer code review |
+| `create_checkpoint()` | `autonomy/run.sh` | Snapshot state |
+| `store_episode_trace()` | `autonomy/run.sh` | Memory storage bridge |
+| `check_human_intervention()` | `autonomy/run.sh` | PAUSE/STOP/INPUT signals |
+| `detect_complexity()` | `autonomy/run.sh` | Auto-detect project complexity |
+| `get_rarv_tier()` | `autonomy/run.sh` | Map iteration to model tier |
+| `check_budget_limit()` | `autonomy/run.sh` | Budget circuit breaker |
+| `is_rate_limited()` | `autonomy/run.sh` | Rate limit detection |
+| `cmd_heal()` | `autonomy/loki` | Legacy system healing |
+| `hook_pre_healing_modify()` | `autonomy/hooks/migration-hooks.sh` | Friction safety gate |
+| `hook_post_healing_modify()` | `autonomy/hooks/migration-hooks.sh` | Characterization test verification |
+| `hook_healing_phase_gate()` | `autonomy/hooks/migration-hooks.sh` | Healing phase transition gate |
+
+### Critical Data Flow
+
+A PRD enters via `loki start` (`autonomy/loki:622`), which execs `run.sh`. The `run_autonomous()` loop (`autonomy/run.sh:10253`) builds prompts via `build_prompt()` (`autonomy/run.sh:8987`) injecting RARV instructions, SDLC phases, memory context, queue tasks, and checklist status. The provider is invoked (Claude via `-p` flag, Codex via `exec --sandbox workspace-write` with `CODEX_MODEL_REASONING_EFFORT` env var, Cline/Aider sequentially). Post-iteration, the system runs checklist verification, app runner management, playwright smoke tests, and code review. Completion is determined by a council vote (`council_should_stop` at `autonomy/completion-council.sh:1605`), completion promise text, or max iterations. All components communicate through `.loki/` filesystem state files.
+
+**Deprecated entrypoints:**
+- `loki run <issue-ref>` is a deprecated alias for `loki start <issue-ref>` since v6.84.0. Emits a `cli_command_deprecated` telemetry event. See `autonomy/loki:4436-4456`. Prefer `loki start`.
+
+The fuller codebase knowledge graph lives in local Claude project memory
+(`~/.claude/projects/<sanitized-repo-path>/memory/CODEBASE-KNOWLEDGE-GRAPH.md`),
+not in this repository. It is not tracked in git and is not shipped in the npm
+package, so it resolves only on a machine where that memory exists. The tables
+above are the in-repo reference and are the authority for anyone else.