loki-mode 9.56.0 → 9.57.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.57.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.57.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-9.56.0
+9.57.0

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.57.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.

package/docs/dev/release-checklist.md

@@ -0,0 +1,157 @@
+# Release checklist and local CI
+
+Moved out of CLAUDE.md (S-78) to keep the root file short. Updated in this
+pass to remove two items that `docs/v10/DECISIONS.md` D25 and
+`docs/LOKI-10-BUILD-PROMPT.md` section 1 have superseded:
+- `git add -A` in step 4 is replaced with staging by name (repo rule, always).
+- Per-merge pushing is replaced by the release-train model (D25): batch
+  approved merges locally, push once per train, freeze main until Tests, Bun
+  Parity and Security Audit are all green on that exact SHA, then release.
+  "Wait for user approval before commit" from the old workflow is superseded
+  by the standing authorization in `docs/LOKI-10-BUILD-PROMPT.md` section 1
+  for sessions operating under that program; outside it, ask as normal.
+
+## Local CI Before Every Push
+
+**The FAST tier is the release gate. The FULL tier is not a blocker.**
+
+Founder decision 2026-07-31: GitHub CI runs Tests in ~31s and Release in ~2min
+via 4-way sharding. The local FULL tier takes ~27min with no sharding, too
+slow for an hourly-or-faster release cadence.
+
+- **Before push/release: `bash scripts/local-ci.sh`** (fast tier, default).
+- **Do NOT block a release on `LOCAL_CI_TIER=full`.** Ship, let GitHub Actions
+  verify, and fix what it finds in the next release train.
+- Run the FULL tier when diagnosing something specific, or on a quiet cycle,
+  not as a release precondition.
+
+**Why the fast tier and not nothing.** Of seven real defects found on
+2026-07-31, four were caught by the local gate ALONE. The sharpest is dist
+freshness: CI never validates that the committed `loki-ts/dist/loki.js`
+matches src; when that slipped, three releases shipped the wrong version.
+
+**The packaged artifact is the blind spot (2026-08-01).** Everything works
+from a git checkout, so no in-repo test and no GitHub CI job can see:
+- quality-gate detector test files missing from npm's `files[]` (v8.38.0)
+- committed `dist/loki.js` hardcoded to a stale version for 27 releases (v8.40.0)
+- `npm pack` content checks that tolerate losing required artifacts (v9.11.0)
+
+Rules that generalize past packaging:
+1. A check that guards the shipped artifact must run in the FAST tier.
+2. Assert each required thing individually, never a count.
+3. Guard against vacuity (an empty capture that makes every assertion pass;
+   `npm pack`'s listing is on STDERR).
+
+`LOCAL_CI_SHARDS` (default 4) controls local sharding; `LOCAL_CI_SERIAL=1`
+forces serial for diagnosis.
+
+After a release ships, run post-release distribution validation:
+- npm: `npm pack loki-mode@<VERSION>`, untar, run `bash package/bin/loki version`
+- Docker: `docker pull asklokesh/loki-mode:<VERSION>`, `docker run --rm <img> version`,
+  `doctor --json`, `status --json`
+- Brew: WebFetch the live formula, verify version + sha256
+- Both routes (Bun + LOKI_LEGACY_BASH=1) on each channel
+
+Cleanup after every local-ci run and post-release validation uses
+`loki_run_tmp_cleanup` (see `docs/dev/tmp-cleanup.md`).
+
+## Release Workflow
+
+**Step 0 (always first): `bash scripts/local-ci.sh`** -- pre-push gate.
+
+### 1. Version Bump - ALL Files
+
+```
+VERSION                                  # Single line: X.Y.Z
+package.json                             # "version": "X.Y.Z"
+SKILL.md                                 # Header (line ~6) AND footer (last line)
+Dockerfile                               # LABEL version= AND org.opencontainers.image.version (both, or it drifts)
+Dockerfile.sandbox                       # Same two labels
+plugins/loki-mode/.claude-plugin/plugin.json  # "version": "X.Y.Z" (marketplace.json carries no version)
+server.json                              # "version" AND packages[loki-mode].version (MCP registry manifest; enforced by tests/test-server-json-current.sh)
+vscode-extension/package.json            # DEPRECATED v7.2.0, no longer published; bump only if vendoring
+CLAUDE.md                                # Version pointer, if present
+dashboard/__init__.py                    # __version__ = "X.Y.Z"
+mcp/__init__.py                          # __version__ = "X.Y.Z"
+CHANGELOG.md                             # Add new version entry at top
+docs/INSTALLATION.md                     # Version header
+wiki/Home.md, wiki/_Sidebar.md, wiki/API-Reference.md
+README.md, docker-compose.yml            # Docker image tags (MAJOR/MINOR bumps)
+```
+
+### 2. Build Dashboard Frontend
+
+```bash
+cd dashboard-ui && npm ci && npm run build:all && cd ..
+ls -la dashboard/static/index.html   # verify >100KB
+```
+`npm publish`'s `prepublishOnly` also triggers this build automatically.
+
+### 3. Run Tests
+
+```bash
+bash -n autonomy/run.sh
+bash -n autonomy/loki
+python3 -c "import ast, os; [ast.parse(open(f'dashboard/{f}').read()) for f in os.listdir('dashboard') if f.endswith('.py')]"
+python3 -c "import json; json.load(open('package.json')); print('JSON OK')"
+cd dashboard-ui && npx playwright test && cd ..   # requires dashboard on 57374
+```
+
+### 3a. Pre-Publish Validation (MANDATORY)
+
+```bash
+npm pack --dry-run 2>&1 | grep -E "web-app/dist|dashboard/static" || echo "FAIL: expected files missing"
+git ls-files web-app/dist/index.html | grep -q . || echo "FAIL: web-app/dist/ not tracked"
+git ls-files dashboard/static/index.html | grep -q . || echo "FAIL: dashboard/static/ not tracked"
+npm pack && npm install -g ./loki-mode-*.tgz
+loki --version
+loki web --no-open &
+sleep 3
+curl -s http://127.0.0.1:57374/ | grep -q "Loki" && echo "PASS: web app serves" || echo "FAIL"
+curl -s http://127.0.0.1:57374/api/status | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null && echo "PASS: API responds" || echo "FAIL"
+loki web stop
+npm install -g loki-mode
+rm -f loki-mode-*.tgz
+```
+If any check fails, do not release; fix the root cause first.
+
+### 4. Commit and land (release-train model, D25)
+
+Stage files by name (never `git add -A` or `git add .`), commit with the
+repo-local `asklokesh` identity, no co-author. Batch approved merges locally;
+push once per train (`git push origin main`); wait for Tests, Bun Parity and
+Security Audit to go green on that exact SHA before bumping VERSION and
+releasing. GitHub Actions then creates the tag, the GitHub Release, publishes
+npm, builds/pushes Docker, and updates the Homebrew tap. Do not manually
+create tags.
+
+### 5. Verify ALL Distribution Channels
+
+```bash
+gh run list --limit 1 && gh run watch <run-id>
+npm view loki-mode version
+npm pack loki-mode --dry-run 2>&1 | grep dashboard/static
+docker pull asklokesh/loki-mode:X.Y.Z && docker run --rm asklokesh/loki-mode:X.Y.Z loki version
+brew update && brew info loki-mode
+gh release view vX.Y.Z
+```
+
+### Distribution Channel Checklist
+
+| Channel | Dashboard API | Dashboard Frontend | Memory System | Skills/References |
+|---------|--------------------------|------------------------------|---------------|-------------------|
+| npm     | `dashboard/*.py`         | `dashboard/static/index.html`| `memory/`     | `skills/`, `references/` |
+| Docker  | `COPY dashboard/`        | Built in Dockerfile or committed | `memory/` | `skills/`, `references/` |
+| Homebrew| Full tarball             | Full tarball                 | Full tarball  | Full tarball |
+| VSCode  | DEPRECATED v7.2.0 -- no longer published | -- | -- | -- |
+| Release | Skill-only zip           | N/A                          | N/A           | `references/` |
+
+### Credentials (GitHub Secrets)
+`NPM_TOKEN`, `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN`, `HOMEBREW_TAP_TOKEN`.
+
+## Testing
+
+```bash
+./benchmarks/run-benchmarks.sh humaneval --execute --loki
+./benchmarks/run-benchmarks.sh swebench --execute --loki
+```

package/docs/dev/research-foundation.md

@@ -0,0 +1,29 @@
+# Research foundation
+
+Moved out of CLAUDE.md (S-78) to keep the root file short. Content unchanged.
+
+Built on 2025 research from three major AI labs:
+
+**OpenAI:**
+- Agents SDK (guardrails, tripwires, handoffs, tracing)
+- AGENTS.md / Agentic AI Foundation (AAIF) standards
+
+**Google DeepMind:**
+- SIMA 2 (self-improvement, hierarchical reasoning)
+- Google DeepMind Robotics (VLA models, planning)
+- Dreamer 4 (world model training)
+- Scalable Oversight via Debate
+
+**Anthropic:**
+- Constitutional AI (principles-based self-critique)
+- Alignment Faking Detection (sleeper agent probes)
+- Claude Code Best Practices (Explore-Plan-Code)
+
+**Academic:**
+- CONSENSAGENT (anti-sycophancy)
+- GoalAct (hierarchical planning)
+- A-Mem/MIRIX (memory systems)
+- Multi-Agent Reflexion (MAR)
+- NVIDIA ToolOrchestra (efficiency metrics)
+
+See `references/openai-patterns.md`, `references/lab-research-patterns.md`, and `references/advanced-patterns.md`.

package/docs/dev/tmp-cleanup.md

@@ -0,0 +1,157 @@
+# Temp directory and process cleanup (mandatory helpers)
+
+Moved out of CLAUDE.md (S-78) to keep the root file short. Content unchanged.
+CLAUDE.md still states the invariant; this file holds the runnable helpers.
+
+## Test and Resource Cleanup (MANDATORY - NEVER SKIP)
+
+**Before reporting ANY task as done, run ALL cleanup steps below. No exceptions.**
+
+1. **Create one run-owned temp directory before the first temp write.** Keep
+   every archive, package extraction, log, PID file, and test fixture for the
+   task below this directory. Never use fixed names or shared globs under
+   `/tmp`.
+
+2. **Stop only processes started by the current task.** Retain their exact PIDs
+   below `$LOKI_RUN_TMP` and signal those PIDs individually. Do not use
+   `pkill`, a shared-port sweep, or a name-pattern kill as cleanup.
+
+3. **Remove only the validated run-owned directory.** Use the helpers below.
+   Cleanup fails closed unless the target is a direct child of the canonical
+   temp root, has the exact ownership marker created with it, is owned by the
+   current UID, still carries the private permissions the helper set (`700`
+   for the directory, `600` for the marker), is not a symlink, and is not a
+   Git worktree. Never replace this with a wildcard deletion under `/tmp` or
+   `$TMPDIR`.
+
+```bash
+loki_run_tmp_create() {
+    local temp_root marker
+
+    if [ -n "${LOKI_RUN_TMP:-}" ]; then
+        printf '%s\n' "LOKI_RUN_TMP is already set; refusing to replace it" >&2
+        return 64
+    fi
+
+    temp_root="$(cd "${TMPDIR:-/tmp}" 2>/dev/null && pwd -P)" || {
+        printf '%s\n' "Cannot resolve the temp root" >&2
+        return 64
+    }
+    LOKI_RUN_TMP="$(mktemp -d "${temp_root}/loki-run.XXXXXXXX")" || return 1
+    marker="${LOKI_RUN_TMP}/.loki-run-owned"
+
+    chmod 700 "$LOKI_RUN_TMP" || {
+        rmdir "$LOKI_RUN_TMP" 2>/dev/null || true
+        unset LOKI_RUN_TMP
+        return 1
+    }
+    if ! printf '%s\n' "$LOKI_RUN_TMP" >"$marker" || ! chmod 600 "$marker"; then
+        rm -f -- "$marker"
+        rmdir "$LOKI_RUN_TMP" 2>/dev/null || true
+        unset LOKI_RUN_TMP
+        return 1
+    fi
+    export LOKI_RUN_TMP
+}
+
+# Read one numeric stat field portably. GNU uses -c, BSD uses -f, and each
+# MISPARSES the other's flag: GNU -f means --file-system and still prints a
+# filesystem block on stdout while exiting non-zero, so a bare `a || b`
+# fallback captures that block and concatenates the real value onto it.
+# Validate the captured value instead of trusting exit status or stream, so a
+# usage string, a filesystem block, an empty result, or a concatenation of any
+# of those is rejected on every platform.
+loki_run_tmp_stat_field() {
+    local gnu_fmt="$1" bsd_fmt="$2" path="$3" value
+
+    value="$(stat -c "$gnu_fmt" -- "$path" 2>/dev/null)" || value=''
+    case "$value" in
+        '' | *[!0-9]*) value="$(stat -f "$bsd_fmt" -- "$path" 2>/dev/null)" || value='' ;;
+    esac
+    case "$value" in
+        '' | *[!0-9]*) return 1 ;;
+    esac
+    printf '%s\n' "$value"
+}
+
+loki_run_tmp_cleanup() {
+    local target temp_root marker marker_value target_real
+    local target_uid marker_uid target_mode marker_mode current_uid
+
+    target="${LOKI_RUN_TMP:-}"
+    [ -n "$target" ] || return 0
+    temp_root="$(cd "${TMPDIR:-/tmp}" 2>/dev/null && pwd -P)" || return 64
+
+    case "$target" in
+        "${temp_root}"/loki-run.*) ;;
+        *)
+            printf '%s\n' "Refusing cleanup outside the run-owned temp namespace: $target" >&2
+            return 64
+            ;;
+    esac
+    [ "$(dirname -- "$target")" = "$temp_root" ] || return 64
+    [ -d "$target" ] && [ ! -L "$target" ] || return 64
+
+    marker="${target}/.loki-run-owned"
+    [ -f "$marker" ] && [ ! -L "$marker" ] || return 64
+    IFS= read -r marker_value <"$marker" || return 64
+    [ "$marker_value" = "$target" ] || return 64
+
+    current_uid="$(id -u)" || return 64
+    target_uid="$(loki_run_tmp_stat_field '%u' '%u' "$target")" || return 64
+    marker_uid="$(loki_run_tmp_stat_field '%u' '%u' "$marker")" || return 64
+    [ "$target_uid" = "$current_uid" ] && [ "$marker_uid" = "$current_uid" ] || return 64
+
+    # Refuse anything readable, writable, or executable by group or other. Only
+    # the low three permission digits are compared: GNU '%a' includes the
+    # setuid/setgid/sticky digit and BSD '%Lp' does not, and `mktemp -d` under a
+    # setgid temp root inherits g+s that a three-digit `chmod 700` preserves.
+    # Comparing the raw value against "700" would therefore read 2700 on Linux,
+    # refuse, and leak the very directory this helper exists to remove.
+    target_mode="$(loki_run_tmp_stat_field '%a' '%Lp' "$target")" || return 64
+    marker_mode="$(loki_run_tmp_stat_field '%a' '%Lp' "$marker")" || return 64
+    # Keep the last three digits, zero-padded, then require exactly 700/600.
+    target_mode="00${target_mode}"
+    marker_mode="00${marker_mode}"
+    [ "${target_mode#"${target_mode%???}"}" = "700" ] || return 64
+    [ "${marker_mode#"${marker_mode%???}"}" = "600" ] || return 64
+
+    target_real="$(cd "$target" 2>/dev/null && pwd -P)" || return 64
+    [ "$target_real" = "$target" ] || return 64
+    [ "$(dirname -- "$target_real")" = "$temp_root" ] || return 64
+
+    # A linked worktree has a .git file; a primary worktree has a .git
+    # directory. Refuse both, including a broken .git symlink.
+    if [ -e "${target}/.git" ] || [ -L "${target}/.git" ]; then
+        printf '%s\n' "Refusing to remove a Git worktree: $target" >&2
+        return 64
+    fi
+
+    rm -rf -- "$target"
+    [ ! -e "$target" ] || return 1
+    unset LOKI_RUN_TMP
+}
+```
+
+4. **Verify exact cleanup.** Confirm each recorded PID is gone and the saved
+   `$LOKI_RUN_TMP` path no longer exists. Do not scan or delete other users'
+   or runs' temp paths.
+
+5. **Report cleanup status** to the user in the task completion message,
+   including only the explicit run-owned path and process IDs handled.
+
+## Feedback Loop Requirement (before documenting a new feature)
+
+1. **Verify it exists** - check files, run commands, test endpoints.
+2. **Run feedback loop** - Task tool with Opus to review claims for accuracy.
+3. **Be factual only** - never document features that don't work yet.
+4. **Mark planned features** - use "Coming Soon" or "Planned" labels.
+
+```bash
+# Before documenting "npm install -g loki-mode"
+npm view loki-mode  # Does package exist on registry?
+# Before documenting a CLI command
+which loki && loki --help
+# Before documenting a file path
+ls -la path/to/file
+```