loki-mode 11.3.0 → 11.3.1

package/docs/R4-TRUST-TRAJECTORY-DESIGN.md

@@ -1,127 +0,0 @@
-# R4: Visible Trust Trajectory - Design Note
-
-Status: implemented in worktree (not yet merged). Author: R4 release team.
-Verified against live source on 2026-06-03 (v7.8.3 worktree base; R1/R3/R5
-already shipped, so the arc is further along than the loki-plan doc states).
-
-## The story no competitor tells
-
-Devin, Cursor, Windsurf, Claude Code, Aider et al. show you a single run.
-None show you whether the agent is getting more trustworthy on YOUR repo over
-time. Loki already runs a 3-reviewer council + RARV-C closure on every run and
-persists the result. R4 makes the resulting TRUST TRAJECTORY visible:
-
-- council approve-rate trending UP
-- gate pass-rate trending UP
-- iterations-to-completion trending DOWN
-- human interventions trending DOWN
-
-If the agent is earning autonomy on this repo, the trajectory shows it. That is
-compounding, repo-specific proof of trust -> stickiness.
-
-## Honest-data rule (non-negotiable)
-
-Every number derives from REAL persisted run records. Never fabricate a trend.
-With fewer than 2 runs, the trajectory is reported as "not enough history yet"
-(insufficient=true), never a fake direction.
-
-## Data source (REUSED, not new)
-
-R3 already established `.loki/proofs/<run_id>/proof.json` as the persistent,
-one-per-run history record (written by `autonomy/lib/proof-generator.py` at run
-completion, on both success and failure, unless `LOKI_PROOF=0`). The R3 cost
-timeline endpoint (`dashboard/server.py` `/api/cost/timeline`) already mines
-this exact directory for per-run cost history.
-
-R4 mines the SAME directory for the trust signals already present in each
-proof.json:
-
-| Trust signal            | proof.json path                          | Notes |
-|-------------------------|------------------------------------------|-------|
-| council pass (per run)  | `council.final_verdict`                  | APPROVE/APPROVED/COMPLETE => pass |
-| council ratio (per run) | `council.reviewers[].vote` (APPROVE/...) | secondary signal when verdict absent |
-| gate pass-rate (per run)| `quality_gates.passed` / `.total`        | already aggregated by generator |
-| iterations (per run)    | `iterations` (int or {count})            | iterations-to-completion |
-| files changed (per run) | `files_changed.count`                    | context, not a trust axis |
-| timestamp               | `generated_at` (ISO 8601)                | ordering axis |
-
-Human interventions: there is no per-run intervention counter persisted in
-proof.json today. Rather than fabricate one or add new instrumentation in this
-slice, R4 reports interventions as a derived best-effort signal ONLY when the
-proof carries it (`council.interventions` or top-level `interventions`), and
-otherwise marks that axis `available=false` with an honest note. This keeps the
-honest-data rule intact and leaves a clean seam for a future per-run
-intervention counter (a one-line add in proof-generator.py).
-
-## Direction calculation (up / down / flat)
-
-For each numeric axis across the time-ordered run series:
-
-1. Split the series into an earlier half and a later half (median split; odd
-   counts drop the middle point so the two halves never overlap).
-2. Compare the mean of the later half vs the earlier half.
-3. delta = later_mean - earlier_mean. Direction:
-   - `flat` if |delta| <= epsilon (epsilon scaled per axis; rates use 0.01).
-   - `up` / `down` by sign of delta.
-4. "Good direction" is axis-specific: higher is better for council/gate pass
-   rates; lower is better for iterations + interventions. The `improving`
-   boolean encodes whether the direction is the good one, so the UI can color
-   green/red without re-encoding the per-axis polarity.
-
-Rationale for half-split vs least-squares slope: half-split is robust to a
-single noisy run, needs no float regression in bash, and is trivially testable
-with fixtures. A 2-run series degrades to last-vs-first, which is correct.
-
-## Persistence (under .loki/metrics/, REUSED dir)
-
-The aggregated trajectory is persisted to
-`.loki/metrics/trust-trajectory.json` (schema_version 1). This is a derived
-cache, written by the `loki trust` command and the dashboard endpoint so other
-surfaces can read a single source of truth. It is NOT authoritative state: it
-is always recomputable from `.loki/proofs/`. Deleting it loses nothing.
-
-## Surfaces
-
-1. CLI: `loki trust [--json]` (NEW Bun-native command, mirrors `loki kpis`
-   exactly). Falls through to a bash `cmd_trust` when bun is absent (kpis had
-   no bash fallback; R4 adds one because the Python derivation is shared and
-   trivial to call from bash, giving real bash+Bun parity).
-   - `loki kpis` stays a single-run snapshot. R4 does NOT duplicate it; `trust`
-     is the across-runs trajectory view. `loki kpis` output gains a one-line
-     pointer to `loki trust` (no behavior change).
-
-2. Dashboard endpoint: `GET /api/trust/trajectory` (NEW, mirrors
-   `/api/cost/timeline`). Reads `.loki/proofs/*/proof.json`, returns the
-   per-run series + per-axis direction + insufficient flag.
-
-3. Dashboard panel: standalone `legacy-ui-static/trust.html` + `/trust` route
-   (mirrors `cost.html` + `/cost`), plus a nav entry and SPA section in
-   `build-standalone.js` (mirrors the cost panel wiring exactly).
-
-4. WS push: the `_push_loki_state_loop` broadcasts a `trust_update` message
-   when the trajectory's overall improving-count changes (mirrors the R3
-   `budget_status` transition push). No new channel; reuses manager.broadcast.
-
-## Parity + no-duplication audit
-
-- Data: reuses `.loki/proofs/` (R1/R3). No new run-time instrumentation.
-- Endpoint: new route, but copies the `/api/cost/timeline` read pattern and
-  the `_proofs_dir()` / `_safe_json_read` helpers verbatim in spirit.
-- Panel: new `trust.html`, structurally a sibling of `cost.html`.
-- CLI: new `trust`, structurally a sibling of `kpis`. `kpis` unchanged except a
-  one-line see-also.
-- Shared derivation: a single Python module
-  (`autonomy/lib/trust_trajectory.py`) is the source of truth; the dashboard
-  endpoint imports it, and the bash `cmd_trust` shells out to it. The Bun
-  command reimplements the same pure logic in TS (parity-tested), matching how
-  `kpis` has both a TS derivation and reads the same JSON the bash side writes.
-
-## Test plan
-
-- Python: `tests/test_trust_trajectory.py` - aggregation from fixture
-  proof.json files, direction calc (up/down/flat) per axis polarity, the
-  insufficient-history (<2 runs) case, no-PII (only derived numbers + run_id +
-  timestamps leave the function), malformed proof.json skipped not fatal.
-- TS: `loki-ts/tests/metrics/trust.test.ts` - same aggregation + direction
-  parity on identical fixtures, insufficient case, JSON/human formatting.
-- All mocked from on-disk fixtures. No provider calls, no paid calls.

package/docs/R5-AUTO-WIKI-DESIGN.md

@@ -1,137 +0,0 @@
-# R5: Auto-wiki + Cited Codebase Q&A (Loki's DeepWiki) -- Design Note
-
-Status: implemented in worktree (do not commit to main). Target release: R5 of the
-competitive-stickiness arc. NO version bump in this worktree.
-
-## Goal
-
-A persistent, queryable per-project wiki generated from the codebase, surfaced in
-the dashboard, with cited answers. Loki's answer to Devin DeepWiki. Sections cite
-the real source files they were built from; `loki wiki ask` returns a grounded,
-cited answer (citations = `file:line`). Generation is incremental: it skips when
-the codebase has not changed (reuses the R1 codebase-signature idea).
-
-## What already exists (verified against source, 2026-06-03)
-
-| Asset | File | Reused? |
-|---|---|---|
-| `loki docs generate` (LLM-written README/ARCHITECTURE/...) | `autonomy/loki:20577` (`cmd_docs`) | Patterns reused: `_docs_scan_project`, `_docs_build_context`, `_docs_invoke_provider`, `_docs_write_manifest`. Not the command itself -- docs has no citations and no Q&A. |
-| Proof-of-run generator (Python core, thin CLI readers) | `autonomy/lib/proof-generator.py`, bash `cmd_proof`, `loki-ts/src/commands/proof.ts` | Architecture precedent reused exactly: Python core does the heavy work; bash + Bun are thin readers; dashboard exposes read APIs. |
-| PII redaction | `autonomy/lib/proof_redact.py` (`redact_tree`, `_redact_paths`) | Reused: wiki output is normalized to repo-relative paths and passed through the redactor so no `/Users/<name>/...` leaks. |
-| Org knowledge graph | `memory/knowledge_graph.py` (`OrganizationKnowledgeGraph`) | Token-overlap scoring idea reused (`_tokenize` / `query_patterns`). NOT a codebase index -- it aggregates `.loki/memory/semantic/*.json` patterns across projects, keyed on `~/.loki/knowledge`. See "Honest reuse" below. |
-| Memory retrieval | `memory/retrieval.py` (`MemoryRetrieval`) | Inspected. It retrieves memory entries (episodic/semantic/procedural), NOT source code. Not a code indexer. Not reused for code retrieval. |
-| Dashboard read-API + traversal-safety | `dashboard/server.py:7191` (`_safe_proof_run_dir`) | Pattern reused for the wiki section/path param (`_safe_wiki_section`). |
-| Dashboard web components | `legacy-ui/components/*.js` (Web Components) | New `loki-wiki-browser.js` follows the same `LokiElement` convention; registered in `index.js`. |
-
-### Honest reuse statement
-
-The task says "reuse memory/knowledge_graph.py and memory/retrieval.py." Both were
-read. Neither is a *codebase* index: `knowledge_graph.py` aggregates cross-project
-*memory patterns* (`.loki/memory/semantic`), and `retrieval.py` retrieves *memory
-entries*, not source files. There was no existing per-file code index to query for
-grounded citations. So R5 adds a new lightweight, dependency-free code index
-(`autonomy/lib/wiki_index.py`) and reuses the parts that genuinely fit: the
-token-overlap retrieval scoring (ported from `knowledge_graph._tokenize` /
-`query_patterns`), the docs scanner, the proof manifest/signature idea, and the
-redactor. Reuse is stated where real; not fabricated to satisfy a constraint.
-
-ChromaDB (`tools/index-codebase.py`, MEMORY.md) is an OPTIONAL future backend. The
-core deliberately does NOT depend on it: it needs Docker + python3.12 and is not
-CI-safe. Default retrieval is deterministic and dependency-light.
-
-## The grounding contract (the part that must be right)
-
-Fabricated citations are made structurally impossible, not merely prompt-discouraged:
-
-1. **Index**: `wiki_index.py` scans source files (git-tracked when available, else a
-   filtered `find`), splits each into line-anchored chunks
-   `{file, start_line, end_line, text}` where `file` is REPO-RELATIVE.
-2. **Retrieve** (`ask`): deterministic token-overlap scoring (no LLM, no network)
-   selects the top-K chunks for the question. Each is a record we own.
-3. **Prompt**: the LLM sees NUMBERED chunks `[1]..[K]` and is told to cite by chunk
-   index only (`[1]`, `[2]`). It never emits raw paths.
-4. **Map + validate**: indices in the answer are mapped back to `{file, start_line}`
-   from the retrieval records. Every citation is then validated against the
-   filesystem (file exists AND start_line <= file length). Non-resolving citations
-   are DROPPED. The LLM can only reference chunks we supplied, and only ones that
-   resolve on disk -- so a fabricated citation cannot survive.
-5. **generate**: per-section "sources" are CODE-DERIVED (the files the scanner read,
-   the real def/class line numbers from a grep parse), not LLM-emitted. The LLM
-   writes prose; the citation list comes from the index.
-
-If the LLM is unavailable (CI, no provider), `ask` returns an EXTRACTIVE answer
-(the top chunk snippets with their real citations) and `generate` writes a
-template-based wiki whose citations are still the real scanned files. No fabrication
-in any path.
-
-## Mocking the LLM in CI
-
-The Python core reads `LOKI_WIKI_LLM_STUB`:
-- unset -> call the real provider via the same path `_docs_invoke_provider` uses
-  (`claude -p` etc.), OR fall back to extractive/template if no provider on PATH.
-- set to a file path -> read the stubbed completion from that file.
-- set to any other value -> use it literally as the completion.
-
-Tests set `LOKI_WIKI_LLM_STUB` so CI makes ZERO paid calls. This mirrors how the
-proof tests fake `gh`/`open` via PATH and env.
-
-## Storage layout (per project, generated)
-
-```
-.loki/wiki/
-  wiki.json              # structured: sections[], each with title, body, citations[]
-  index.md               # human-readable rendered wiki (overview + module list)
-  architecture.md        # rendered architecture section
-  modules.md             # rendered key-modules section
-  data-flow.md           # rendered data-flow section
-  wiki-manifest.json     # signature (git sha + per-file content hash), generated_at
-  code-index.json        # the chunk index (file, start_line, end_line, tokens)
-```
-
-NOTE: `.loki/wiki/` (this deliverable, per-project, generated, gitignored) is a
-DIFFERENT namespace from the repo-root `wiki/` (the GitHub wiki in the release
-workflow). R5 never touches the latter.
-
-## Incremental regeneration (R1 signature idea)
-
-`wiki-manifest.json` stores a `signature` = sha256 over (git HEAD sha + sorted list
-of `path:content-hash` for every scanned source file). `loki wiki generate` computes
-the current signature; if it equals the stored one, it SKIPS regeneration and prints
-"up to date" (unless `--force`). This is the same cheap-incremental idea as the docs
-manifest and the R1 codebase signature.
-
-## Command surface
-
-```
-loki wiki generate [path] [--force]   # build/refresh .loki/wiki/ (incremental)
-loki wiki show [section]              # print rendered wiki (or one section)
-loki wiki ask "<question>"           # grounded, cited answer (file:line)
-```
-
-## Build surface (mirrors the proof precedent)
-
-- `autonomy/lib/wiki_index.py` -- scan + chunk + token-overlap retrieve + signature
-  (importable module; underscore name).
-- `autonomy/lib/wiki-generator.py` -- generate wiki.json + rendered md (LLM or
-  template), citations code-derived; subprocess-invoked (hyphen in name, like
-  proof-generator.py).
-- `autonomy/lib/wiki-ask.py` -- retrieve K chunks, prompt (stub-aware), map + validate
-  citations, print grounded answer. Subprocess-invoked.
-- bash `cmd_wiki` in `autonomy/loki` (generate|show|ask) -- thin dispatcher to Python.
-- Bun `loki-ts/src/commands/wiki.ts` -- native `show` (reads `.loki/wiki/`); `generate`
-  and `ask` delegate to the bash/Python core (heavy work, provider). Added to the
-  `bin/loki` allowlist and `cli.ts` switch.
-- Dashboard: `GET /api/wiki` (list sections + manifest), `GET /api/wiki/{section}`,
-  `POST /api/wiki/ask` -- all traversal-safe; web component `loki-wiki-browser.js`.
-
-## Tests
-
-- `tests/test_wiki_index.py` -- chunking is line-accurate; retrieval is deterministic;
-  signature stable + changes on edit; repo-relative paths only.
-- `tests/test_wiki_generator.py` -- generate on a fixture repo; citations point to REAL
-  files; incremental skip when unchanged; LLM stubbed; no absolute paths (no PII).
-- `tests/test_wiki_ask.py` -- `ask` returns grounded answer; every citation resolves on
-  disk; a stub that emits a bogus `[99]` index is dropped (anti-fabrication).
-- `tests/cli/test-wiki-command.sh` -- bash route generate/show/ask on a fixture, stubbed.
-- `loki-ts/tests/commands/wiki.test.ts` -- Bun `show` parity with the rendered md.
-- `tests/dashboard/test_wiki_routes.py` -- API list/get/ask + traversal rejection.

package/docs/R6-ROLLBACK-CHECKPOINT-PLAN.md

@@ -1,107 +0,0 @@
-# R6: 1-Click Rollback + Checkpoint UX (Design Note)
-
-Status: implemented in this worktree (not committed to main). For integrator cherry-pick.
-Goal: make Loki's existing checkpoint/rollback infra EXCELLENT and OBVIOUS so users
-run autonomous work boldly, knowing a mistake is one action from undone.
-
-## 1. Verified existing code (read, not assumed)
-
-### Checkpoint writers (THREE divergent formats, one shared index.jsonl)
-
-| Writer | ID format | Files captured | Source |
-|---|---|---|---|
-| `create_checkpoint()` (automatic, per iteration) | `cp-{iter}-{epoch}` | `state/orchestrator.json`, `autonomy-state.json`, `queue/{pending,completed,in-progress,current-task}.json` | `autonomy/run.sh:7373` |
-| `cmd_checkpoint create` (manual CLI) | `cp-{ts}` | `session.json`, `dashboard-state.json`, `queue/`, `memory/`, `metrics/`, `council/` (recursive copy) | `autonomy/loki:16122` |
-| `POST /api/checkpoints` (dashboard) | `chk-{ts}` | `dashboard-state.json`, `session.json`, `queue/` | `dashboard/server.py:5085` |
-
-All three append to `.loki/state/checkpoints/index.jsonl` (field names differ; the
-dashboard `GET /api/checkpoints` normalizes them).
-
-### Restore (rollback) paths
-
-| Path | Restores | Source |
-|---|---|---|
-| `rollback_to_checkpoint()` (internal, run.sh) | state + queue json (NOT autonomy-state) | `autonomy/run.sh:7473` |
-| `loki checkpoint rollback <id>` (bash CLI) | glob-restores whatever is in the cp dir | `autonomy/loki:16263` |
-| `loki rollback to|latest <id>` (Bun) | the 5 RESTORE_FILES | `loki-ts/src/commands/rollback.ts` + `loki-ts/src/runner/checkpoint.ts:632` |
-
-### Bun runner checkpoint API (`loki-ts/src/runner/checkpoint.ts`, 700 lines)
-- `createCheckpoint`, `listCheckpoints`, `readCheckpoint`, `rollbackToCheckpoint` (planner),
-  `executeRollback` (copier). Byte-for-byte parity with bash `create_checkpoint`.
-- `metadata.json` keys are pinned by `loki-ts/tests/runner/checkpoint.test.ts:62-91`
-  (`Object.keys(m).sort()`) -- they MUST NOT change.
-
-### Dashboard
-- `GET /api/checkpoints`, `GET /api/checkpoints/{id}`, `POST /api/checkpoints` exist.
-- The UI component `legacy-ui/components/loki-checkpoint-viewer.js` (601 lines) ALREADY
-  renders list + create + rollback-with-two-step-confirm and POSTs to
-  `POST /api/checkpoints/{id}/rollback` -- but that endpoint **did not exist**. The
-  dashboard rollback button was DEAD.
-
-## 2. Three decisions (verified facts, not assumptions)
-
-### Decision A: what "truly undo an iteration" restores
-Verified fact: Loki does NOT commit per iteration (`grep "git commit" autonomy/run.sh`
-finds only merge-conflict `git add`, no per-iteration commit). Therefore the captured
-`git_sha` is HEAD (the last commit), and `git reset --hard <git_sha>` would discard the
-iteration's work PLUS anything since the last commit -- it cannot reconstruct a specific
-iteration's working tree. The pre-existing printed hint `git reset --hard <git_sha>`
-(run.sh:7541, loki:16314) was therefore actively MISLEADING.
-
-Resolution: capture a real working-tree snapshot at checkpoint time via `git stash create`
-(captures tracked changes without disturbing the tree), then ANCHOR it with
-`git update-ref refs/loki/cp/<id> <sha>` so `git gc` cannot prune the dangling commit.
-The snapshot sha is written to a SIDECAR file `worktree-snapshot.txt` in the checkpoint
-dir (NOT metadata.json, to preserve byte parity). Restore of code is opt-in
-(`loki rollback to <id> --code`) because it overwrites tracked files; by default the
-durable, correct recovery command is printed: `git stash apply refs/loki/cp/<id>`.
-
-State + `.loki/CONTINUITY.md` (the iteration/conversation handoff context) are
-auto-restored -- this is the always-on "undo the iteration's state + context".
-
-Honest gap: `git stash create` captures tracked changes only; it does NOT capture
-untracked or ignored files. Files the iteration newly ADDED and never committed are not in
-the snapshot, and an apply will not delete them. Documented, not hidden.
-
-### Decision B: re-undoability invariant
-Every restore path FORCES a pre-rollback snapshot of current state before overwriting, so
-a rollback is itself trivially undoable. The Bun `executePlan`, the dashboard endpoint, and
-bash `cmd_rollback` all create a forced checkpoint first (bash `create_checkpoint`
-early-returns on a clean tree, so the new code path forces it). The human dashboard path
-ALSO keeps the existing two-step confirm. Autonomous paths never block on a prompt.
-
-### Decision C: do not add a 4th format, do not unify the 3
-Unifying would break the byte-for-byte parity test; a 4th compounds the problem. The new
-dashboard restore endpoint GLOB-restores whatever the checkpoint dir contains (mirrors bash
-`cmd_checkpoint rollback`), so it works for all three writers. New fields go in sidecars.
-
-## 3. Changes (parity-organized)
-
-- **bash `autonomy/loki`**: add top-level `rollback)` dispatch + `cmd_rollback`
-  (`list|show|to|latest`, `--code` flag). `to|latest` delegate to the existing
-  `cmd_checkpoint rollback` restore body after forcing a pre-rollback snapshot, then
-  optionally apply the anchored code snapshot. Prominent "you can undo this" output.
-- **bash `autonomy/run.sh`**: `create_checkpoint` also copies `CONTINUITY.md`, creates +
-  anchors the worktree snapshot (sidecar), echoes the checkpoint id; `rollback_to_checkpoint`
-  also restores `CONTINUITY.md` and forces the pre-rollback snapshot. The per-iteration call
-  site emits a prominent "Checkpoint <id> created -- undo with `loki rollback to <id>`".
-  The misleading `git reset --hard` hint replaced with `git stash apply refs/loki/cp/<id>`.
-- **Bun `loki-ts/src/runner/checkpoint.ts`**: copy `CONTINUITY.md` into the checkpoint
-  (additive, parity-safe), add `CONTINUITY.md` to RESTORE_FILES, expose
-  `executeRollbackWithSnapshot` that forces a pre-rollback snapshot before restoring.
-  metadata.json keys unchanged.
-- **Bun `loki-ts/src/commands/rollback.ts`**: `executePlan` forces a pre-rollback snapshot
-  before restoring; HELP text made honest about state+context restore and the printed code
-  command.
-- **dashboard `dashboard/server.py`**: add `POST /api/checkpoints/{id}/rollback`
-  (`require_scope("control")`, `_sanitize_checkpoint_id`, forced pre-snapshot, glob-restore).
-  Un-deads the existing UI button.
-
-## 4. Tests (extend existing suites, no parallels)
-- `loki-ts/tests/runner/checkpoint.test.ts`: CONTINUITY round-trip restore + forced
-  pre-rollback snapshot.
-- `loki-ts/tests/commands/rollback.test.ts`: `to` forces a pre-rollback snapshot (re-undo).
-- `tests/test-checkpoint-cli.sh`: top-level `loki rollback list|to|latest`, restore actually
-  reverts, pre-rollback snapshot exists.
-- `dashboard/tests/test_rollback_endpoint.py`: POST rollback reverts, scope, 404.
-No paid model calls anywhere.

package/docs/R7-ZERO-CONFIG-FIRST-RUN-PLAN.md

@@ -1,137 +0,0 @@
-# R7: Zero-config killer first run (time-to-first-value)
-
-Design note for the R7 release in the competitive-stickiness arc. Worktree
-deliverable for the integrator to cherry-pick. NO version bumps here.
-
-## Goal
-
-Convert trials to habits. The #1 acquisition-to-retention gate is the first
-run. Today a blank first run is mediocre and Loki's deep RARV-C / council can
-feel heavy on run 1. R7 = a frictionless first run: a user types
-`loki start "<one line>"` (or `loki start` in an existing repo) and sees a
-VISIBLE valuable artifact in minutes, with depth opt-in later.
-
-Honest "fast": we do NOT fake progress. We actually shorten the path by running
-a lightweight execution profile first (capped iterations, completion council
-off, simple complexity tier, heavy phases off) so the first visible artifact
-plus a proof-of-run land quickly. "Go deeper" = re-run plain `loki start` for
-the full RARV-C depth.
-
-## Verified current behavior (real code, traced 2026-06-03)
-
-- `cmd_start()` (`autonomy/loki:746`) is the unified entry. It parses args,
-  calls `detect_arg_type()` (`autonomy/loki:667`), then dispatches:
-  issue -> `cmd_run`; prd -> sets `prd_file`; empty -> no-PRD path; unknown
-  -> treated as a PRD path for back-compat.
-- `cmd_start` ends in `_loki_new_session_exec "$RUN_SH" ...` (`autonomy/loki:1678`).
-  Every branch of `_loki_new_session_exec` (`autonomy/loki:167-186`) uses
-  `exec`, so NOTHING after that line in `cmd_start` runs. Any end-of-run
-  message must live in `run.sh`, not after the exec in `cmd_start`.
-- `cmd_quick()` (`autonomy/loki:8849`) already synthesizes a PRD from a
-  one-line task and sets the lightweight profile
-  (`LOKI_MAX_ITERATIONS=3`, `LOKI_COMPLEXITY=simple`,
-  `LOKI_COUNCIL_ENABLED=false`, heavy phases off), then execs `run.sh`.
-- No-PRD + generated-PRD-reuse (v7.8.1): in `run.sh` around line 11102,
-  `decide_generated_prd_action()` (`run.sh:4032`) returns reuse|update|generate
-  for the no-arg in-repo path; signature persisted by
-  `persist_prd_signature_if_present()` (`run.sh:4064`).
-- Proof-of-run (R1): `generate_proof_of_run()` (`run.sh:4101`) wraps
-  `autonomy/lib/proof-generator.py`. It runs at session end (`run.sh:13312`)
-  on both success and failure, gated only by `LOKI_PROOF` (NOT by council
-  state), writing `.loki/proofs/<run_id>/{proof.json,index.html}`. Viewable
-  via `loki proof list` / `loki proof open <id>` (Bun-routed, `bin/loki:119`).
-
-### The exact gap R7 closes (traced, not assumed)
-
-`loki start "build a todo app"` TODAY:
-1. `detect_arg_type("build a todo app")` returns `unknown` (has spaces, no
-   extension, not a file, not an issue ref).
-2. The PRD-not-found guard at `autonomy/loki:1243` and `:1268` only fires for
-   `*.md|*.json|*.txt|*.yaml|*.yml`, so a brief with spaces slips past.
-3. `prd_file="build a todo app"` is passed to `run.sh`, which fails:
-   `[ERROR] PRD file not found: build a todo app`.
-
-So the one-line-brief path is broken today. R7 makes it work. This is ADDITIVE:
-no existing valid input (`.md` PRD, issue ref, single-token name) changes
-behavior.
-
-## Design (additive, no behavior change to existing inputs)
-
-1. `detect_arg_type`: add a `brief` return ONLY for args that contain
-   whitespace and match none of the file/issue/path patterns. A single-token
-   `unknown` arg still falls back to PRD path (back-compat preserved).
-2. `--brief "<text>"` explicit flag: deterministic escape hatch for the rare
-   single-word brief (e.g. `loki start --brief "snake"`).
-3. Shared helper `synthesize_brief_prd <file> <text>`: factored so `cmd_quick`
-   and the new brief path write the same forward-looking PRD. The brief PRD is
-   written to `.loki/brief-prd-$$.md` -- DISTINCT from `.loki/generated-prd.md`
-   so it never pollutes the v7.8.1 generated-PRD-reuse signature logic
-   (generated-prd is for codebase analysis of an existing repo; brief is a
-   forward spec).
-4. `cmd_start` brief sub-path: set the lightweight TTFV profile (same env as
-   quick), synthesize the brief PRD, set `LOKI_TTFV=brief`, then continue
-   through the normal exec path. Upfront framing ("fast first pass") is printed
-   BEFORE the exec.
-5. `cmd_start` no-arg in-repo path: UNCHANGED execution (existing no-PRD +
-   reuse, full RARV-C depth), but set `LOKI_TTFV=repo` so the end-of-run
-   what-next framing appears.
-6. `run.sh` end-of-session: after proof generation, when `LOKI_TTFV` is set and
-   stdout is a TTY, call `print_ttfv_next_steps <mode> <result>`. The wording
-   BRANCHES on mode so the message always matches what actually ran:
-   - `brief`: lightweight first pass, council off; proof has diffs/cost/time
-     (NO council verdicts, because the council was disabled).
-   - `repo`: full-depth codebase analysis, council on; proof has
-     diffs/cost/time/council verdicts.
-   Both point at `loki proof list` / `loki proof open` (the visible artifact)
-   and the depth opt-in. Gated so it is silent in CI / pipes and never fires
-   for normal PRD runs. Factored into `print_ttfv_next_steps` so it is
-   unit-testable.
-
-Honesty note: the `brief` message intentionally does NOT advertise "council
-verdicts" because brief mode runs with the council off (`_collect_council` in
-proof-generator.py finds no council state, so that proof section is blank on the
-brief path). The `repo` message claims verdicts because the full-depth path runs
-the council. This keeps the end-of-run summary truthful per the no-fabrication
-rule.
-
-### Why fast is honest
-
-The brief path uses the same lightweight profile `cmd_quick` already ships:
-3 iterations max, council off, simple tier, heavy phases (perf, a11y,
-regression, UAT, web-research) off. That genuinely shortens the path to first
-visible value. We do not print fake progress or claim work that did not happen;
-the proof-of-run is generated from real `.loki/` state. Depth is opt-in: the
-end-of-run message tells the user to re-run plain `loki start` (or
-`loki start <prd.md>`) for the full council-gated build.
-
-## Parity (bash + Bun)
-
-`loki start` and `loki quick` are NOT in the Bun shim allowlist
-(`bin/loki:119`), so dispatch is bash-only by design; this change is bash-only
-for the CLI surface. The runtime pieces it reuses are already shared across
-routes: `proof-generator.py` (one implementation, both routes) and the no-PRD /
-generated-PRD-reuse path in `run.sh` (both routes source run.sh). No Bun CLI
-change is required for parity.
-
-## Files
-
-- `autonomy/loki`: `detect_arg_type` brief return; `--brief` flag;
-  `synthesize_brief_prd` helper; `cmd_quick` refactor to use it; `cmd_start`
-  brief sub-path + `LOKI_TTFV` wiring; help text.
-- `autonomy/run.sh`: end-of-session TTFV what-next block.
-- `tests/cli/test_zero_config_first_run.sh`: new test suite.
-
-## Tests (no paid runs; mock via early exit)
-
-Following `tests/cli/test_start_run_unified.sh`: extract `detect_arg_type` and
-`synthesize_brief_prd` in a subshell and assert on them; force `cmd_start` to
-exit before `run.sh` boots via `--provider nonexistent-provider`.
-
-- `detect_arg_type("build a todo app")` = `brief`; single tokens still `unknown`;
-  `.md` still `prd`; issue refs still `issue`; empty still `empty`.
-- `synthesize_brief_prd` writes a PRD containing the brief text and TTFV markers.
-- `loki start "<brief>"` enters the brief path (lightweight env, not
-  "PRD file not found").
-- `loki start --brief "<one word>"` works.
-- existing-repo no-arg path still routes to no-PRD (unchanged).
-- `loki start <prd.md>` (real PRD) still routes to PRD mode (no regression).

package/docs/R8-SHAREABLE-TEAM-ASSETS-PLAN.md

@@ -1,129 +0,0 @@
-# R8: Shareable Team Assets - Design Note
-
-Status: implemented in this worktree (isolated; not committed to main).
-Goal (per arc): turn individual setup into org lock-in / network effects by
-making a team's invested assets EXPORTABLE and IMPORTABLE across a team or org,
-so setup compounds into shared value (the skills-marketplace stickiness dynamic).
-
-## 1. Inventory of existing machinery (verified against real source)
-
-Before writing anything, the existing export/import/share + memory machinery
-was read in full. Findings:
-
-| Mechanism | Location | What it actually does | Reused? |
-|---|---|---|---|
-| `cmd_export` | `autonomy/loki:6254` | Per-run SESSION SNAPSHOT: json / markdown / csv / timeline of one `.loki/` run. Not portable across teams, not redacted. | Reused its `_export_check_overwrite` guard. |
-| `cmd_import` | `autonomy/loki:4722` | Imports GitHub ISSUES into `.loki/queue/`. Unrelated to assets. | Not applicable (different domain). |
-| `cmd_share` | `autonomy/loki:25147` | Uploads a session REPORT as a GitHub gist. | Not applicable (report, not assets). |
-| `cmd_memory` | `autonomy/loki:14475` | Lists/show cross-project learnings in `~/.loki/learnings/*.jsonl`. No tarball export. | Same source dir reused as an asset category. |
-| `proof_redact.py` | `autonomy/lib/proof_redact.py` | Single redaction chokepoint (R1). `redact_tree(obj)`, `redact_value(s)`, `set_context()`, `RULES_VERSION`. | REUSED as-is. No second redactor written. |
-| agent registry | `agents/types.json` | Shipped agent types. `cmd_agent` (`autonomy/loki:19509`) reads it from the install dir. | Bundled as the `agents` category. |
-| PRD templates | `templates/*.md` | 21 templates; read from `$SKILL_DIR/templates` at runtime (`autonomy/loki:9781`, `8840`). | Bundled as `templates`. |
-| council config | `<project>/.loki/council/*.json` | `config.json` / `state.json` (`autonomy/loki:16688`, `autonomy/run.sh:3643`). | Bundled as `council`. |
-| project memory | `<project>/.loki/memory/{episodic,semantic,skills,...}` (`autonomy/run.sh:3183`) | Per-project episodic/semantic/procedural memory. | Bundled as `memory`. |
-| R5 wiki | `<project>/.loki/wiki/**` (`autonomy/loki:22881`) | Cited per-project wiki. | Bundled as `wiki` (opt-in). |
-
-Key negative finding: there is NO separate per-user "custom agent" store.
-"Custom agents" == the `agents/types.json` registry. We do not invent one
-(that would be the parallel-machinery trap the task forbids).
-
-## 2. Why `loki assets` is NOT a duplicate of `cmd_export`
-
-- `cmd_export` = per-run session snapshot, one format at a time, not redacted,
-  not portable. Scope: "what happened in this run".
-- `loki assets` = portable, redacted, multi-category TEAM-ASSET tarball.
-  Scope: "the reusable setup a team invested in", designed to travel to
-  another clone/org. Different scope, different artifact, different lifetime.
-
-Concrete reuse (not a fork): `_export_check_overwrite` (overwrite guard) and
-the `proof_redact` chokepoint. No new redactor, no parallel exporter.
-
-## 3. Asset map and the deliberate export/import asymmetry
-
-| Category | Export source | Bundle path | Import restore root |
-|---|---|---|---|
-| learnings | `~/.loki/learnings/*.jsonl` | `learnings/` | `$HOME/.loki/learnings` |
-| memory | `<project>/.loki/memory/**` | `memory/` | `<cwd>/.loki/memory` |
-| agents | `$SKILL_DIR/agents/types.json` | `agents/` | `<cwd>/agents` |
-| templates | `$SKILL_DIR/templates/*.md` | `templates/` | `<cwd>/templates` |
-| council | `<project>/.loki/council/*.json` | `council/` | `<cwd>/.loki/council` |
-| wiki (opt-in) | `<project>/.loki/wiki/**` | `wiki/` | `<cwd>/.loki/wiki` |
-
-The export and import repo_root values are DELIBERATELY DIFFERENT (enforced in
-`cmd_assets`, not in the Python helper):
-
-- EXPORT reads agents/templates from the loki install (`$SKILL_DIR`), because
-  that is where a team's edited registry/templates live and are read at
-  runtime.
-- IMPORT writes agents/templates under the caller's cwd (the target clone
-  root) BY DEFAULT, NEVER silently back into the install. Writing into
-  `$SKILL_DIR` would clobber the live install with redacted copies (this was
-  caught and fixed during development: a bash smoke test that used `$SKILL_DIR`
-  on import overwrote the worktree's real `agents/types.json` and templates;
-  default restore root changed to cwd, damage reverted).
-- `loki assets import --into-install` opts back into `$SKILL_DIR` for
-  agents/templates only, so a GLOBAL-INSTALL user (the primary install path per
-  CLAUDE.md) gets them read at runtime. This is the symmetric round-trip
-  (export reads $SKILL_DIR, import --into-install writes $SKILL_DIR). It is
-  opt-in because the default cwd target is non-destructive.
-
-memory/learnings/council/wiki restore to `$HOME/.loki` or `<cwd>/.loki` and
-take effect immediately regardless of the flag.
-
-## 4. Redaction (single chokepoint, all file types)
-
-`autonomy/lib/assets_bundle.py` calls `proof_redact.set_context(home, repo)`
-then dispatches by extension before any byte is written into the tarball:
-- `.json` -> parse -> `redact_tree` -> reserialize
-- `.jsonl` -> per-line parse -> `redact_tree` -> reserialize
-- `.md` / `.txt` / other -> `redact_value` on the whole string
-
-Originals on disk are never modified (verified by test). Secrets seeded into
-each of md, jsonl, and json are all stripped (verified by test + live leak
-scan).
-
-Scope of redaction (honest): proof_redact strips SECRETS / KEYS / TOKENS /
-connection-string credentials / absolute home+repo PATHS, per its frozen
-`RULES_VERSION`. It does NOT do general PII (emails, author names, free text).
-The accurate claim for this feature is "no secrets/keys/home-paths leak," not
-"no PII." The authoritative evidence is the leak-scan test
-(`test_imported_assets_contain_no_secrets`), not the manifest count.
-
-## 5. Honest gaps / limitations
-
-- agents/templates restore relative to cwd by default; loki reads them from its
-  install at runtime, so a global-install user should pass `--into-install` (or
-  copy the restored `agents/` + `templates/` into their install). Documented in
-  `--help` and the module docstring. memory/learnings/council/wiki are
-  effective immediately.
-- Round-trip is SEMANTICALLY FAITHFUL but REFORMATTED, not byte-identical:
-  JSON files come back `indent=2`, and JSONL merge canonicalizes lines
-  (sort_keys). Content/semantics are preserved; whitespace/key-order are not.
-- The export-reads-install / import-writes-cwd asymmetry lives in the bash
-  `cmd_assets`, not the Python helper. The Python tests pass roots explicitly
-  so they cover the helper mechanics; the bash asymmetry is covered by
-  `tests/test_assets_cli.sh` (export with SKILL_DIR=A, import from cwd=B,
-  assert agents land in B).
-- The manifest `redactions` count covers structured (json/jsonl) redactions
-  only; `redact_value` (md/text) and path collapses are not counted (the
-  redaction still HAPPENS). The authoritative no-PII evidence is the
-  `test_imported_assets_contain_no_secrets` leak-scan test, not the count.
-- `agents/types.json` and `templates/*.md` are repo-shipped defaults; a bundle
-  from a fresh checkout re-ships the stock set. Value = captured team DELTAS
-  travelling with the baseline.
-- The placement tests assert files land at the mapped path; they do not assert
-  the importing loki reads them at runtime (that is the global-install gap
-  above).
-
-## 6. bash + Bun parity
-
-`assets` is NOT in the `bin/loki` Bun allowlist (`bin/loki:119`), so it falls
-through the shim's default branch to the bash CLI (`bin/loki:145`), exactly like
-`bench`. Parity is free via fall-through; no Bun command is needed or added.
-
-## 7. Files
-
-- `autonomy/lib/assets_bundle.py` (new) - bundler/redactor/restorer helper.
-- `autonomy/loki` (modified) - `cmd_assets` + dispatch case.
-- `tests/test_assets_bundle.py` (new) - 13 tests.
-- `docs/R8-SHAREABLE-TEAM-ASSETS-PLAN.md` (this note).