loki-mode 11.3.0 → 11.3.1

package/docs/ARCHITECTURE-OVERVIEW.md

@@ -1,209 +0,0 @@
-# Loki Mode - Architecture Overview
-
-Spec in, verified product out. This document gives a SIMPLE view for a first read
-and a FULL view for the whole machine, plus one RARV-C iteration as a sequence.
-
-Every claim is verified against source (`autonomy/loki`, `autonomy/run.sh`,
-`autonomy/completion-council.sh`, `skills/quality-gates.md`, `SKILL.md`). Line
-numbers drift; function names are stable. See `CLAUDE.md` for the file map.
-
----
-
-## SIMPLE flowchart (the whole product in five boxes)
-
-```mermaid
-flowchart LR
-    SPEC[Spec: PRD / issue / OpenAPI / one-liner] --> LOOP[RARV-C loop]
-    LOOP --> VERIFY[Verify: gates + council + evidence gate]
-    VERIFY -- not done --> LOOP
-    VERIFY -- verified --> SHIP[Deployed product + proof-of-run]
-```
-
-Diagram type: flowchart. 4 nodes.
-
-Reason, Act, Reflect, Verify, then Closure. The loop does not exit until the
-verify stage clears; "done" is a verdict the machine has to earn, not a claim it
-gets to make.
-
----
-
-## USER view: how you run it and what you get
-
-```bash
-# One-time: launch Claude Code with autonomous permissions
-claude --dangerously-skip-permissions
-
-# Then either say "Loki Mode", or run the CLI directly:
-loki start ./prd.md            # PRD-mode (a Markdown spec file)
-loki start owner/repo#123      # issue-mode (a GitHub issue)
-loki start                     # one-line brief, answer the prompt
-```
-
-What happens: `loki start` (`cmd_start` in `autonomy/loki`) execs the runner
-(`autonomy/run.sh`). The `run_autonomous()` loop builds a prompt each iteration
-(`build_prompt()`), invokes the provider, then runs checklist verification, an app
-runner, smoke tests, and code review. It stops when the completion council votes
-stop (`council_should_stop` in `autonomy/completion-council.sh`), a completion
-promise is met, max iterations is hit, or (v8.0.0) a failure is positively
-identified as non-retryable -- bad credentials, unknown model, exhausted quota --
-where further retries would be guaranteed-identical failures
-(`loki-ts/src/runner/retry_class.ts`, `LOKI_SMART_RETRY=0` to disable). An
-unrecognized failure stays transient and retries as before, so the early exit
-can never abandon a build that would have succeeded.
-
-The council's own force-stop valves (stagnation, repeated done-claims) are
-additionally delayed by one iteration when the agent's self-reported confidence
-spikes, so a sudden claim of near-certainty is VERIFIED rather than trusted
-(`loki-ts/src/runner/council.ts`, v8.0.0). That delay is strictly additive: it
-can only add a verification pass, never skip one, and it never delays the
-stagnation valve.
-
-What you get:
-- A runnable artifact (the built product in your working directory).
-- A proof-of-run: `.loki/proofs/<id>/proof.json` plus an HTML report
-  (`autonomy/lib/proof-generator.py`, `autonomy/lib/proof-template.html`).
-- An honest verdict. The evidence gate blocks completion on an empty diff, red
-  tests, an unhealthy serveable app (runtime-boot axis), or a leaked credential in
-  the changed files (secret-leak axis) - v8.0.0, `SKILL.md`.
-
-Provider-agnostic (stable since v5.0.0): Claude (Tier 1, full), Cline (Tier 2),
-Codex and Aider (Tier 3, degraded, sequential), opencode (sequential). With
-`LOKI_PROVIDER` unset, auto-detection picks the first installed provider in that
-order (`providers/loader.sh:191`); an explicit choice always wins. Gemini was
-removed as a provider in v7.5.18. See `skills/providers.md`.
-
----
-
-## FOUNDER view: the moat
-
-The moat is not "an agent that writes code". It is the trust layer wrapped around
-the loop.
-
-- RARV-C rigor. Every iteration is Reason, Act, Reflect, Verify, then Closure
-  (findings injection, override council, learnings, handoff). The closure knobs
-  are default-on in the Bun runner: `LOKI_INJECT_FINDINGS`, `LOKI_OVERRIDE_COUNCIL`,
-  `LOKI_AUTO_LEARNINGS`, `LOKI_HANDOFF_MD` (`CLAUDE.md`, `skills/quality-gates.md`).
-- Verify, not vibes. 8 quality gates (`skills/quality-gates.md`), a blind
-  3-reviewer council with severity blocking, an anti-sycophancy Devil's Advocate on
-  unanimous PASS, and a verified-completion evidence gate that blocks on positive
-  fabrication evidence. The system does not call work done until it is verified
-  (`SKILL.md`).
-- Tier routing. Opus for planning/architecture, Sonnet for development, Haiku for
-  unit tests and simple parallel work (`CLAUDE.md` Model Selection;
-  `get_rarv_tier()` in `autonomy/run.sh`, session-pinned via `LOKI_SESSION_MODEL`,
-  default sonnet). Cost tracks the tier, not a flat premium.
-- Model-equivalence thesis (founder framing). The rigor lives in the HARNESS (the
-  loop, the gates, the council, the evidence gate), not in any one model. Because
-  the harness is provider-agnostic with abstract model tiers and a degraded mode
-  for non-Claude providers, the trust guarantee is not tied to a single vendor
-  (`SKILL.md` provider-agnostic section; `providers/*.sh`). An optional Anthropic
-  Agent SDK route exists behind `LOKI_SDK_MODE` (off by default, v8.0.0); unset is
-  byte-identical to the claude-CLI route (`references/sdk-mode.md`).
-
----
-
-## FULL flowchart (CLI dispatch to shipped proof)
-
-```mermaid
-flowchart TD
-    subgraph CLI[autonomy/loki - CLI]
-      START[loki start spec] --> DISPATCH[main dispatch]
-      DISPATCH --> EXEC[exec run.sh]
-    end
-
-    subgraph RUNNER[autonomy/run.sh - orchestration]
-      EXEC --> RA[run_autonomous loop]
-      RA --> CPX[detect_complexity]
-      CPX --> TIER[get_rarv_tier / LOKI_SESSION_MODEL]
-      TIER --> BP[build_prompt: RARV + SDLC + memory + queue + checklist]
-      BP --> INV[invoke provider]
-      INV --> ACT[Act: agent edits code]
-      ACT --> CHK[checklist verification]
-      CHK --> APP[app runner + playwright smoke]
-      APP --> CR[run_code_review: 3 blind reviewers]
-    end
-
-    subgraph GATES[Quality gates - skills/quality-gates.md]
-      CR --> G1[1 static analysis]
-      G1 --> G2[2 test suite red blocks]
-      G2 --> G3[3 blind council Crit/High block]
-      G3 --> G4[4 devils advocate on unanimous PASS]
-      G4 --> G5[5 mock integrity HIGH blocks]
-      G5 --> G6[6 test mutation HIGH blocks]
-      G6 --> G7[7 doc coverage]
-      G7 --> G8[8 magic modules debate BLOCK]
-    end
-
-    subgraph CLOSURE[RARV-C closure + memory]
-      G8 --> FIND[inject findings]
-      FIND --> OC[override council on BLOCK]
-      OC --> LEARN[auto learnings]
-      LEARN --> HAND[handoff md]
-      HAND --> MEM[store_episode_trace: episodic/semantic]
-    end
-
-    subgraph VERDICT[Completion decision]
-      MEM --> EG[evidence gate: empty-diff / red-tests / boot / secret-leak]
-      EG --> CC[council_should_stop vote]
-    end
-
-    CC -- keep going --> RA
-    CC -- stop / verified --> PROOF[proof-generator.py -> .loki/proofs/ID/proof.json + HTML]
-    PROOF --> SHIP[deployed product + proof-of-run]
-```
-
-Diagram type: flowchart. 28 nodes across 6 subgraphs.
-
-Verified anchors: `main` dispatch and `cmd_start` in `autonomy/loki`;
-`run_autonomous()`, `build_prompt()`, `run_code_review()`, `detect_complexity()`,
-`get_rarv_tier()` in `autonomy/run.sh`; the 8-gate table in
-`skills/quality-gates.md`; closure env vars in `CLAUDE.md`; `council_should_stop()`
-in `autonomy/completion-council.sh`; proof generation in
-`autonomy/lib/proof-generator.py`. The evidence-gate axes are quoted from
-`SKILL.md` (v8.0.0).
-
----
-
-## One RARV-C iteration (sequenceDiagram)
-
-```mermaid
-sequenceDiagram
-    participant Runner as run_autonomous (run.sh)
-    participant Prompt as build_prompt
-    participant Provider as Provider (Claude/Cline/Codex/Aider/opencode)
-    participant Verify as Gates + council
-    participant Evidence as Evidence gate
-    participant Council as completion council
-    participant Memory as Episodic/semantic store
-
-    Runner->>Prompt: Reason - assemble prompt (RARV, SDLC, memory, queue, checklist)
-    Prompt-->>Runner: iteration prompt
-    Runner->>Provider: Act - invoke provider
-    Provider-->>Runner: code edits + output
-    Runner->>Runner: Reflect - checklist, app runner, smoke tests
-    Runner->>Verify: Verify - 8 gates + 3 blind reviewers
-    Verify-->>Runner: gate verdicts (Crit/High block)
-    Runner->>Runner: Closure - inject findings, override council, learnings, handoff
-    Runner->>Memory: store episode trace
-    Runner->>Evidence: verified-completion evidence gate
-    Evidence-->>Runner: pass / block (empty-diff, red-tests, boot, secret-leak)
-    Runner->>Council: council_should_stop vote
-    Council-->>Runner: continue OR stop (verified)
-    Note over Runner,Council: on continue, next iteration re-enters Reason with injected findings
-```
-
-Diagram type: sequenceDiagram. 7 participants, 14 messages.
-
-Verified: the RARV cycle (Reason/Act/Reflect/Verify) is `SKILL.md` PRIORITY 2; the
-Closure stage maps to the four default-on closure env vars in `CLAUDE.md`; the
-evidence-gate axes and "does not call work done until verified" are `SKILL.md`
-v8.0.0; the council vote is `council_should_stop` in `autonomy/completion-council.sh`.
-
----
-
-## Where this connects
-
-Loki Mode is the ENGINE. Its `proof.json` is the evidence that the neutral
-Autonomi Verify signer stamps, and the Autonomi SaaS product is the hosted layer
-that drives the engine for non-technical users. See `docs/AUTONOMI-ECOSYSTEM.md`
-for the three-repo boundary map.

package/docs/AUTONOMI-ECOSYSTEM.md

@@ -1,107 +0,0 @@
-# The Autonomi Ecosystem
-
-Three repos, three jobs, three clean boundaries. This is the map that ties them
-together.
-
-- loki-mode (this repo) - the ENGINE. Spec to verified product via the RARV-C
-  loop, 8 quality gates, the completion council, and the evidence gate.
-- autonomi-verify - the TRUST layer. A neutral signer that stamps observed evidence
-  with a host-held key so a receipt is non-forgeable and independently checkable.
-- autonomi-saas - the hosted PRODUCT. Plain-English builds for non-technical users,
-  driving the engine and stamping every result with Verify.
-
-Deep dives: `docs/ARCHITECTURE-OVERVIEW.md` (engine),
-`../autonomi-verify/docs/INTEGRATION-DIAGRAMS.md` (trust layer),
-`../autonomi-saas/docs/PRODUCT-ARCHITECTURE.md` (product).
-
----
-
-## The ecosystem in one graph
-
-```mermaid
-graph TD
-    subgraph PRODUCT[autonomi-saas - hosted product, proprietary]
-      WEB[web SPA: prompt-left / output-right]
-      BFF[BFF: only tier with engine token]
-      WORKER[worker: build loop, D-gen, preview, attestor]
-      WEB --> BFF --> WORKER
-    end
-
-    subgraph ENGINE[loki-mode - engine, source-available]
-      CLI[loki CLI + FastAPI]
-      LOOP[RARV-C loop + 8 gates + council + evidence gate]
-      PROOF[proof.json + proof-of-run HTML]
-      CLI --> LOOP --> PROOF
-    end
-
-    subgraph TRUST[autonomi-verify - neutral signer]
-      VAPI[POST /verify: decide then sign]
-      KEY[host Ed25519 key, host only]
-      VAL[POST /validate: check signature, no code run]
-      VAPI --> KEY
-      KEY --> VAL
-    end
-
-    WORKER -->|api-client HTTP| CLI
-    PROOF -->|observed evidence| WORKER
-    WORKER -->|POST evidence| VAPI
-    KEY -->|signed Evidence Receipt| WORKER
-
-    CLIUSER[CLI / CI user] -->|loki start| CLI
-    CLIUSER2[third-party pipeline] -->|loki verify stamp| VAPI
-    ANYONE[anyone with a receipt] -->|validate| VAL
-```
-
-Diagram type: graph. 14 nodes across 3 subgraphs plus 3 external actors.
-
-Verified anchors: the BFF is the only tier holding the engine token
-(`autonomi-saas/apps/bff/src/engine.ts`); the worker attestor POSTs evidence to the
-signer and gets a signed receipt (`autonomi-saas/worker/src/adapters/attestor.ts`);
-the signer decides then signs with a host-only Ed25519 key
-(`autonomi-verify/src/api/index.ts`, `autonomi-verify/src/persistence/index.ts`);
-`/validate` checks a signature without running code
-(`autonomi-verify/src/api/validatePage.ts`); the engine produces `proof.json`
-(`loki-mode/autonomy/lib/proof-generator.py`, `loki-ts/src/runner/proof.ts`).
-
----
-
-## Where each boundary is
-
-| Concern | loki-mode (engine) | autonomi-verify (trust) | autonomi-saas (product) |
-|---|---|---|---|
-| Runs the build | Yes | No | No (delegates to engine) |
-| Decides the verdict | Yes (gates, council, evidence gate) | Yes (neutral re-decide on presented evidence) | No |
-| Holds the signing key | No | Yes (host only) | No |
-| Runs untrusted code | Yes (sandboxed) | No (never runs code) | Via engine + worker sandbox |
-| Multi-tenant auth / billing | No | Per-tenant API key on /verify | Yes (product concern) |
-| Hosted preview + UI | No | No | Yes |
-| Design generation (D-gen) | Prompt-level, engine-agnostic | No | Yes (default-on directive) |
-| Source posture | Source-available | Source-available | Proprietary hosted |
-
-The three-way trust property: the engine can decide, but the PRODUCT that built the
-app does not hold the key that signs the receipt. Only the neutral TRUST layer does.
-That separation is what lets a skeptic believe a receipt without trusting the
-builder. A competitor who self-signs their own success badge cannot offer that.
-
----
-
-## The flow, end to end
-
-1. A user describes an app in the SaaS, or a developer runs `loki start`, or a
-   third-party pipeline runs `loki verify stamp`.
-2. The engine runs the RARV-C loop until the gates, council, and evidence gate
-   clear, producing `proof.json`.
-3. The observed evidence (diff + test signal) is POSTed to the neutral signer,
-   which applies one honest verdict rule and signs with the host-only key.
-4. The signed Evidence Receipt comes back. Anyone can validate its signature at
-   `/validate` without running code or trusting the builder.
-
-Honesty invariants that hold across all three:
-- `verified` means "no fabrication evidence", not "tests are green"
-  (`autonomi-verify/src/verifier/verify.ts`).
-- Block only on positive fabrication evidence; inconclusive is pass-through
-  (`autonomi-verify/src/verifier/evidenceGate.ts`).
-- The design/beauty layer never alters the VERIFIED verdict
-  (`autonomi-saas/docs/AUTONOMI-BUILD-PLAN.md`).
-- Signing happens after the verdict is decided, so signing cannot change it
-  (`autonomi-verify/src/api/index.ts`).

package/docs/COCKPIT-SPEC.md

@@ -1,72 +0,0 @@
-# Loki Cockpit (rec #6) - build spec
-
-> **Historical:** this describes the classic dashboard, removed in Loki Mode 10.8. The Control Plane is the only UI; see [control-plane-migration.md](control-plane-migration.md).
-
-Status: IN BUILD (v7.126.0 target). Design approved via mockup
-(scratchpad/loki-cockpit.html). Grounded in real engine state + Autonomi identity.
-
-## Product model (locked with founder)
-
-Three surfaces, each for a different moment; the cockpit ADDS a choice, removes nothing:
-- `loki start` - launch. Now DETACHES to background by default on an interactive
-  TTY, after a rich handoff (spec/path/tier/budget/logs/dashboard URL + actions:
-  view/watch/dashboard/detach/stop). Auto-picks "Both" after an 8s timeout.
-  CI / --bg / --yes / non-interactive skip the handoff -> exactly today's behavior.
-- `loki cockpit` - NEW opt-in observability surface. Renders the approved cockpit
-  UI live from `.loki/` state, multi-repo. Two render paths:
-    1. In-terminal 4K image (Kitty / iTerm2 / WezTerm / Ghostty graphics protocol)
-       - pixel-exact, the approved HTML/SVG rasterized in-pane.
-    2. Browser-dashboard fallback (default everywhere else) - opens the existing
-       web dashboard (redesigned to the same identity).
-  (`loki watch` is UNCHANGED - it remains the PRD-file auto-rerun watcher.)
-- `loki dashboard` - the web view (redesigned to the cockpit identity).
-- `loki stop` - already exists; surfaced as an action in the handoff + cockpit.
-
-## Identity (from ~/git/autonomi-website, verified)
-
-- Logo: purple squircle #553DE9 + white "A" (two strokes + Q-bezier apex) + teal
-  dot #1FC5A8. Always visible top-left.
-- Accent #553de9 (light) / #8b7bf5 (dark). Teal #1FC5A8 secondary.
-- Fonts: Fraunces (display), Inter (body), JetBrains Mono (mono). Ink #201515.
-- Light-grey ground DEFAULT (#f1f2f6); dark mode optional.
-- Semantic: verified #1f8a52, warning #9a6a12, failed #b23a3a.
-
-## Data sources (real, no new state invented)
-
-- Multi-repo run list: `dashboard/registry.py` -> `get_fleet_runs()` /
-  `list_projects()` reading `~/.loki/dashboard/projects.json`.
-- Per-run live state: `<target>/.loki/autonomy-state.json` (iteration, phase,
-  status), `.loki/council/*.json` (votes, gate/evidence blocks),
-  `.loki/verify/evidence.json` (verdict + gates + freshness), `.loki/events.json`.
-- Budget: `.loki/metrics/` + state cost fields.
-
-## Render pipeline (dependency-free - the "no one has done this" bar)
-
-No chafa / no headless Chrome hard dependency. Pipeline:
-1. Build an SVG of the cockpit from live state (exact fonts embedded, exact colors).
-2. Rasterize SVG -> PNG via a bundled pure path (resvg-js if present, else a
-   node canvas fallback; capability-detected).
-3. Encode PNG -> terminal via a SELF-CONTAINED encoder (Kitty graphics protocol
-   or iTerm2 inline-image escape, pure base64 - no external binary).
-4. Capability detection: $TERM / $TERM_PROGRAM / KITTY_WINDOW_ID / terminal
-   query; on unsupported terminals fall back to opening the browser dashboard.
-   Honest: never claim an image render happened when it fell back.
-
-## Stories
-
-- S1 (start handoff + detach-default): cmd_start. Rich handoff card, 8s auto-Both,
-  actions, remember-per-project. Non-interactive/CI/--bg/--yes bypass. Tests.
-- S2 (loki cockpit command + multi-repo model): cmd_cockpit, reads registry +
-  per-run state, run switcher, --once/--follow, browser fallback. Tests.
-- S3 (render pipeline): SVG-from-state builder + SVG->PNG + terminal-image
-  encoder + capability detection + fallback. Tests (encoder byte-shape, detection).
-- S4 (dashboard identity redesign): apply logo/purple/fonts/multi-repo switcher to
-  legacy-ui; rebuild dist. Lightweight gate.
-- S5 (docs + wiki + release): help text, README, wiki, CHANGELOG, 14 version files.
-
-## Constraints
-
-- CLI-invariant: no existing command changes behavior (watch stays PRD-watcher;
-  start's non-interactive path byte-identical).
-- Never fake-green: image path honest about fallback; every claim tested.
-- Both routes where relevant; bash-route for start/cockpit/stop.

package/docs/COCKPIT-UX-MANDATE.md

@@ -1,53 +0,0 @@
-# loki start opening experience - UX / engagement / stickiness mandate
-
-Founder mandate (2026-07-09): the moment `loki start` opens must deliver the best
-UX, engagement, and stickiness in the CLI space - "nothing anyone ever attempted
-with cli and terminal." This shapes S1 (start handoff) and a dedicated polish pass.
-
-## Principles
-
-1. Time-to-first-wow < 1 second. The instant the user hits enter, they see a
-   crafted, branded, alive moment - not a wall of logs. The Autonomi mark renders
-   immediately; the build identity (spec, tier, what it is about to do) reads at a
-   glance.
-2. Alive, not static. A subtle, tasteful motion on open (the RARV loop igniting,
-   a one-line "here is the plan" reveal). No gratuitous animation; one orchestrated
-   moment that lands.
-3. Confidence + control in the same breath. The user immediately understands: it
-   is running, it is safe, and here is exactly how to watch / steer / stop. The
-   handoff card IS the hook - it makes staying to watch feel rewarding.
-4. Stickiness = the cockpit pull. "Both" (dashboard + cockpit) is the default and
-   the card sells it: "watch it build, live." First run teaches `loki cockpit`;
-   the remembered choice makes the second run instant.
-5. Progress you feel. Show the first real signal fast (tier detected, first
-   iteration reasoning) so the user gets a dopamine hit of momentum, not a spinner.
-6. Honest always. Never fake progress or a wow that is not backed by real state.
-
-## Concrete asks (for the polish pass after slices merge)
-
-- A crafted open banner: Autonomi logo + "Loki" wordmark (Fraunces feel in ASCII/
-  unicode), a one-line value framing of THIS run, then the handoff card.
-- The countdown to auto-Both should feel inviting ("opening your cockpit in 8s -
-  press a key to choose"), not like a timeout to dread.
-- The reattach hints after detach should be delightful + copy-pasteable
-  (`loki cockpit` front and center).
-- Optional: a tiny "what Loki will do" 3-line plan preview (from detected tier +
-  spec) so the user sees intent before backgrounding.
-- Measure: time-to-first-frame, and whether users pick Both (engagement proxy).
-
-This is a follow-up polish story (S6) layered on S1 once the core lands. Do not
-fake it; every wow is backed by a real field.
-
-## HARD CONSTRAINTS (founder, 2026-07-09)
-
-- STARE-WORTHY: the open must be a VISUAL moment people stop and admire - the
-  quality of a crafted product launch screen, in the terminal. Type, spacing,
-  the Autonomi mark, colors (truecolor), and one alive beat. Not a log dump.
-- ZERO NEW TOOLING / ZERO FRICTION: the user installs NOTHING extra and learns NO
-  new tool. No chafa, no headless Chrome as a requirement, no new binary, no
-  config step. It must work out of the box on `loki start`. The dependency-free
-  pure-bash render path (truecolor ANSI + optional in-terminal image where the
-  terminal already supports it, silent graceful fallback otherwise) is mandatory;
-  anything that would make a user run an install command is disqualified.
-- IT JUST HAPPENS: the amazing open is the DEFAULT of `loki start`, not an opt-in
-  flag the user must discover. No extra ceremony.