loki-mode 7.128.1 → 7.129.0

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.128.1
+**Version:** v7.129.0
 
 ---
 
@@ -396,7 +396,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.128.1 start ./my-spec.md
+  asklokesh/loki-mode:7.129.0 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/docs/RARV-C-100X-PLAN.md

@@ -0,0 +1,278 @@
+# RARV-C 100x Native-Primitives Upgrade - Plan (v8.0.0 arc)
+
+## Context
+
+Founder mandate (memory `project-rarvc-cookbook-upgrade`): we can't out-build
+Replit/Emergent/Cognition on capability. Loki's moat is loop RIGOR (never-fake-green
+RARV-C, 3-reviewer council, evidence gate), which is ON-THESIS with Anthropic's own
+long-running-agent guidance. The gap isn't rigor; it's efficiency: the loop does its
+mechanics via home-grown bash (parsing model output as TEXT, polling for budget,
+inferring cost from token math) where the installed `claude` CLI now ships NATIVE
+primitives that do the same job cheaper, faster, and without fragile parsing.
+
+This plan adopts those primitives where they MEASURABLY beat the bash equivalents, one
+per commit, bench-proven, quality never regresses. MAJOR arc (v8.0.0) on branch
+`feature/rarv-c-100x-primitives` (not yet created).
+
+**The honest headline: much of this is already shipped.** Two prior plan docs exist
+(`docs/RARV-C-LOOP-EFFICIENCY-PLAN.md`, `docs/RARV-C-CHANGE-MAP.md`, grounded to v7.121.5),
+AND the engine has since adopted several native flags. So this plan does NOT regenerate
+them. It: (1) reconciles drift to v7.128.2, (2) records what's ALREADY adopted so we don't
+rebuild it, (3) scopes the genuinely net-new work (extend structured-outputs to 4 remaining
+text-parse sites), (4) adds the missing PARITY and RELEASE sections, and consolidates into
+`docs/RARV-C-100X-PLAN.md`.
+
+---
+
+## Primary-source verification (done live this session, CLI v2.1.207)
+
+Per `reference-claude-session-flags` ("live-probe, don't trust stale training or --help
+alone"), every flag was verified by RUNNING it:
+
+| Primitive | Flag | Verified behavior (2026-07-13) |
+|---|---|---|
+| Structured output | `--json-schema <schema>` | Forces valid JSON. Envelope carries top-level `structured_output` key + `result` valid-JSON + `stop_reason:"tool_use"`. Model CANNOT emit malformed output. |
+| Cost breaker | `--max-budget-usd <amt>` | On exceed: `subtype:"error_max_budget_usd"`, `is_error:true`, exit 0 (graceful, parseable). |
+| Effort dial | `--effort low\|medium\|high\|xhigh\|max` | 5 levels; maps onto `get_rarv_tier()`. |
+| Rate-limit resilience | `--fallback-model <model>` | Present. |
+| Caching visibility | JSON envelope | `usage.cache_creation.ephemeral_1h_input_tokens` vs `ephemeral_5m` per call -> caching measurable. |
+| Cost/iter readout | JSON envelope | `total_cost_usd`, per-model `costUSD`, `cache_read_input_tokens`, `iterations[]`. |
+| Continuity | `--resume`/`--session-id`/`--fork-session` | iter0 `--session-id U0`, iterN `--resume U0`; `--session-id` reuse ERRORS. |
+
+---
+
+## What is ALREADY adopted (do NOT rebuild - ponytail rung 2)
+
+Verified in current source. The prior CHANGE-MAP predates these:
+
+- **`--effort` + `--max-budget-usd` are ALREADY plumbed** in `_loki_build_claude_auto_flags`
+  (`providers/claude.sh:143-158`), gated on `loki_claude_flag_supported` (degrades on old CLI),
+  mirrored in `loki-ts/src/providers/claude_flags.ts` (`effortForTier()`:23, `buildAutoFlags()`:150).
+  So "adopt native budget/effort breakers" is LARGELY DONE. `check_budget_limit()` (`run.sh:13035`)
+  and `is_rate_limited()` (`run.sh:12835`) still exist as the belt to the native suspenders.
+- **`--json-schema` is ALREADY adopted for the council-vote path**: `voter-agents.sh:277`
+  (`claude --agents <json> --json-schema <schema>`), wired as PREFERRED council dispatch at
+  `completion-council.sh:3137-3144` with graceful text-parse fallback (3146-3154). Schema:
+  `loki-ts/data/finding-schema.json`. TS mirror: `loki-ts/src/council/voter_agents.ts:299-327`.
+  This pair is the TEMPLATE to extend, not a greenfield build.
+- **Completion detection is already structured** via `.loki/signals/*` + `loki_complete_task`
+  MCP tool (`run.sh:13351-13369`); text-match is legacy behind `LOKI_LEGACY_COMPLETION_MATCH=true`.
+
+**Net-new structured-output work = extend the voter-agents+schema template to the 4 remaining
+text-parse sites. Everything else is tuning + bench + pointing side-calls at flags that exist.**
+
+---
+
+## Reconciled anchors (v7.128.2; lines drift, re-grep before editing)
+
+**completion-council.sh:** `_council_effective_min_iter()`:118 | `COUNCIL_CHECK_INTERVAL`:84 |
+`COUNCIL_STAGNATION_LIMIT`:132 | `council_evidence_gate()`:1704 | explicit-claim fast path:3640
+(block 3625-3648) | modulo gate now in helper `_council_should_check_now()`:3521-3560 (gate:3548),
+called from `council_should_stop`:3644 | `council_should_stop()`:3562
+
+**run.sh:** `detect_complexity()`:2491 | `get_rarv_tier()`:2616 | `run_code_review()`:11095 |
+`is_rate_limited()`:12835 | `check_budget_limit()`:13035 | `store_episode_trace()`:13729 |
+`save_state()`:14395 | `build_prompt()`:14633 | `run_autonomous()`:16299 | `LOKI_SESSION_MODEL`
+default:742, session-pin read:16959, case block:16963-16967 | `[CACHE_BREAKPOINT]` INERT (doc anchor
+only, no cache wiring):15143/15231/15278 | APP_CRASHED injection:14969 (python3 -c inline)
+
+**Main-loop invocation:** `run.sh:17316-17320` -> `claude "${_loki_claude_argv[@]}" -p "$prompt"
+--output-format stream-json --verbose` (argv ~17226+). Uses stream-json, not --json-schema.
+Model catalog: opus->claude-opus-4-8, sonnet->claude-sonnet-5, haiku->claude-haiku-4-5; defaults
+planning/development/fast ALL=sonnet (v7.104.0).
+
+### The 4 remaining text-parse sites (the genuine structured-output targets)
+1. **Code-review verdict** `run.sh:11044-11063` `_classify_verdict` (regex `grep -iE "VERDICT:"`
+   -> case FAIL/PASS/AMBIGUOUS, no retry) + severity greps :11075/:11090; reviewer call :10998
+   uses `--output-format text`. Parity-locked to `loki-ts/src/runner/quality_gates.ts`.
+2. **Council VOTE fallback** `completion-council.sh:645-659` (`grep -oE VOTE:`) + `:1005` (Python
+   `re.search`) - the fallback under the already-structured path; mangled VOTE silently->REJECT.
+3. **Council-v2 JSON** `council-v2.sh:337-346` (`sed -n '/^{/,/^}/p'` carves JSON from prose, else
+   hardcodes REJECT); invocation :299 (no schema).
+4. **Done-recognition** `done-recognition.sh:282-303` (`json.loads` + brace-substring fallback,
+   else `inconclusive`); call :57/:171 (no schema).
+
+---
+
+## Deliverable 1: Bench harness (BUILD/LOCK THIS FIRST - nothing ships before it)
+
+Reuse `benchmarks/bench/` (~95% built per existing plan S2a). The work is lock + reconcile +
+baseline, not a build:
+- **Lock a discriminator-derived corpus** (existing plan 2e-HARDENING #3): simple + HARD (tier-guard)
+  + MULTI-FAILURE (parallel-fix) + TOKEN-HEAVY (distillation), each with machine-checkable held-out
+  acceptance. Frozen once baselined.
+- **Reconcile iterations source** to `events.jsonl` `iteration_complete` count (canonical) with
+  session.json fallback, so `adapters/loki.py` and `speed-benchmark.sh` agree. PREREQUISITE, blocking.
+- **NEW (from live probe):** read cost/cache/iterations straight from the `--json-schema`/`--output-format
+  json` envelope (`total_cost_usd`, `cache_read_input_tokens`, `iterations[]`) instead of token-math x
+  price-table where available - more accurate, self-consistent with the CLI.
+- **Noise floor** (blocking): baseline reports SPREAD (std/min-max across trials); a change ships only
+  if its metric moves BEYOND the noise band. Effect < trial variance -> "no measurable effect", don't ship.
+- **2-spec smoke check** (the one runnable guard): one MUST-pass, one underspecified MUST-fail; assert
+  `verified_pass == [True, False]`. If the grader can't tell them apart it measures nothing.
+- **Commit the v7.128.2 baseline** (`benchmarks/results/<baseline>.json`, N real OFF-WORKTREE builds,
+  isolated source copy, cwd + LOKI_TARGET_DIR pinned to scratch) BEFORE any change.
+- **Grader stays deterministic** `success = exit==0` on held-out acceptance. NEVER council/completion-claim.
+  `validate_adapter_output()` already rejects self-judged keys - keep that invariant.
+
+**Gate rule (binding, every change):** ships iff it improves >=1 of {iterations, $/build, wall-clock}
+beyond the noise band AND does not regress verified-pass-rate on the frozen corpus vs baseline.
+
+---
+
+## Deliverable 2: Primitive-by-primitive adoption table (ranked, one per commit)
+
+Bucket key: **(a)** orchestration/flags, changeable now | **(b)** founder-gated (build_prompt
+byte-lock) | **(c)** needs off-worktree real-build validation.
+
+| # | Primitive / change | Current impl (file:line) | Native replacement | Expected win | Bucket | Parity | Rollback |
+|---|---|---|---|---|---|---|---|
+| 1 | **Structured code-review verdict** | `run.sh:11044` regex `_classify_verdict` + severity greps :11075/:11090; reviewer :10998 `--output-format text` | reviewer emits `--json-schema` (extend `voter-agents.sh`+`finding-schema.json` template); read `structured_output.verdict/severity` | Kills fragile parse + AMBIGUOUS-token bugs; zero retry. Quality-safety, not speed | (a) | safe (invocation flag, NOT build_prompt); MUST mirror in `quality_gates.ts` | keep text fallback path (like council does 3146-3154) |
+| 2 | **Structured council VOTE** (retire text fallback) | `completion-council.sh:645/1005` regex/re.search fallback | make the already-wired `--json-schema` path (3137) the only path; delete text fallback once proven | Removes silent VOTE->REJECT corruption (:2337) | (a) | safe; TS mirror `voter_agents.ts` | revert to fallback |
+| 3 | **Structured council-v2** | `council-v2.sh:337-346` sed-carved JSON | add `--json-schema` + `--output-format json` to :299 | Removes "prose around JSON"->hardcoded REJECT | (a) | safe | hardcoded-REJECT fallback stays |
+| 4 | **Structured done-recognition** | `done-recognition.sh:282-303` json.loads+brace-slice | add `--json-schema` to :57/:171 | Removes unparsable->inconclusive | (a) | safe | inconclusive fallback stays |
+| 5 | **Council interval sweep** (existing CHANGE-MAP #1) | `completion-council.sh:84` interval=5 | tune 2-3 for simple tier | fewer idle iters -> $/wall-clock | (a) | n/a | env default |
+| 6 | **Complexity->tier routing** (existing #3) | `run.sh:742` flat sonnet; case :16963 | `auto` arm: simple->haiku-enable, complex->opus-pin | $/build on simple majority | (c) | 3 readers + hard-guard | revert to `sonnet` |
+| 7 | **Native budget/effort tighten** | ALREADY plumbed `claude.sh:143-158`; side-calls (:10998, council-v2:299, done-rec:57) still bare | point side-calls at `--max-budget-usd`/`--effort` too | consistent native breaker everywhere | (a) | mirror bash<->TS flags | drop flag |
+| 8 | **Prompt caching** (existing #7, CONTINGENT) | `[CACHE_BREAKPOINT]` INERT `run.sh:15143` | wire real `cache_control` on static prefix IF CLI folds it across per-iter processes | $/build on multi-iter (cache reads visible in envelope) | (b)-adjacent | verify CLI first; may be no-op | remove marker wiring |
+| 9 | **Self-heal from logs** (existing #4) | APP_CRASHED count only `run.sh:14969`; LAST_ERROR write-only | route `tail+grep` error signature into prompt | pass-rate on crashing specs | (c) | build_prompt-adjacent -> check byte-lock | honest-degrade to today |
+
+Ranked order to execute: **1 -> 2 -> 3 -> 4** (structured-outputs cluster, all bucket-(a),
+parity-safe, mostly quality/robustness - do first, low risk) **-> 5** (interval, zero code)
+**-> 7** (side-call flag tighten) **-> 6** (tier routing, (c)) **-> 9** (self-heal, (c)) **-> 8**
+(caching, contingent, verify CLI first). Each: change, re-run corpus, apply gate rule. No bench
+move the right way = don't ship (ponytail: no no-ops).
+
+**Do NOT** touch `build_prompt()` output text (items that would: 8, 9 partially) without founder
+auth + 60-fixture regen. Structured-outputs items 1-4 do NOT touch build_prompt - confirmed
+parity-safe below.
+
+---
+
+## Deliverable 3: Parity plan
+
+**The load-bearing fact:** the 60-fixture SHA-256 lock (`loki-ts/tests/parity/build_prompt.test.ts`,
+KNOWN_FAILING empty = hard 60/60) hashes ONLY `buildPrompt()` return TEXT. CLI flags come from a
+separate surface (`claude_flags.ts` / `voter_agents.ts` / `providers.ts:244`). **So adding
+`--json-schema`/`--effort`/`--max-budget-usd` to a claude call is parity-SAFE w.r.t. the lock**, and
+also doesn't touch the 10-command CLI matrix (which never invokes a model).
+
+**The parity TRAP this arc must own** (agent-verified): a native flag added to ONE route only
+(bash `autonomy/lib/claude-flags.sh` vs TS `loki-ts/src/providers/claude_flags.ts`) would **pass all
+four parity gates** (bun-parity.yml, parity-drift.yml, local-ci matrix, build_prompt lock) while
+diverging at RUNTIME - because the matrix doesn't spawn the model. Therefore:
+- **Every native-flag change lands in BOTH `claude-flags.sh` AND `claude_flags.ts`, byte-mirrored**,
+  gated on `claudeFlagSupported()`/`loki_claude_flag_supported` for old-CLI degrade.
+- **Proven by the flag-parity unit tests** (`loki-ts/tests/runner/providers.test.ts`,
+  `tests/test-bash-bun-parity.sh` run at `local-ci.sh:390`), NOT the CLI matrix. Add a case per new flag.
+- Structured-output items 1-4: mirror the bash change (voter-agents/council-v2/done-rec/quality-gates)
+  in the corresponding TS (`council/voter_agents.ts`, `runner/quality_gates.ts`).
+- **build_prompt-touching items (8, 9)**: founder-gated. Regenerate all 60 fixtures via `run-bash.sh`
+  (`for i in $(seq 1 60); do bash run-bash.sh fixture-$i; done`), regenerate `index.json`, keep bash<->TS
+  60/60 in the SAME PR. Watch the fixtures 27/45 alphabetical-readdir determinism guard.
+- **Doctor normalizers are TRIPLICATED** (`bun-parity.yml:127-184`, `parity-drift.yml:83-135`,
+  `local-ci.sh:812-860`) with subtle diffs (JSON floor-vs-delete, counts kept-vs-blanked). If any
+  primitive changes doctor output, edit ALL THREE in sync.
+
+Every commit proven on BOTH routes (`bin/loki` + `LOKI_LEGACY_BASH=1 bin/loki`).
+
+---
+
+## Deliverable 4: Gate plan
+
+- **Trust-core = 3-reviewer council** (2 Opus + 1 Sonnet, unanimous APPROVE, reviewers RUN tests).
+  Any CONCERN/REJECT -> read source, fix, RE-RUN whole council. Loop to 3/3. Never "2-of-3".
+- **`bash scripts/local-ci.sh` green before EVERY push** (Step 0). It mirrors every workflow:
+  bash -n + shellcheck, pytest, `bun typecheck` + `bun test` (the 60-fixture lock runs here),
+  CLI dual-route (`test-cli-commands.sh` Bun + LEGACY_BASH), `test-bash-bun-parity.sh`, the local
+  bun-parity matrix, npm-pack contents (>=6 load-bearing files), SBOM, no-emoji, no-`git add -A`.
+- **Extraction-test harness for bash fn changes** (`feedback-function-extraction-test-harness`):
+  extract the changed fn AND every helper it calls (grep `sed -n '/^<fn>() {/'` tests); `set +u`
+  inside the eval subshell; prove runtime-vs-test before "fixing" a red test (fix the TEST if runtime
+  is right, never patch correct code).
+- **RARV-C changes proven with hermetic Bun integration tests** (stub judge, `LOKI_OVERRIDE_REAL_JUDGE=0`,
+  mkdtemp scratch, no token cost) - pattern in `loki-ts/tests/integration/override_on_block.test.ts`.
+- **Never run an engine build from the worktree** (`feedback-never-run-engine-build`): all real builds
+  from isolated source copy, cwd + LOKI_TARGET_DIR pinned to scratch.
+
+---
+
+## Deliverable 5: Release plan (v8.0.0, MAJOR)
+
+- **14 version locations** (all verified at 7.128.2, zero drift): VERSION:1, package.json:4,
+  SKILL.md:6+411, Dockerfile:9/14, Dockerfile.sandbox:102/103, plugins/.../plugin.json:5, CLAUDE.md:306,
+  dashboard/__init__.py:10, mcp/__init__.py:60, CHANGELOG.md:8, docs/INSTALLATION.md:5(+399 docker tag),
+  wiki/Home.md:106, wiki/_Sidebar.md:46, wiki/API-Reference.md:69.
+- **MAJOR bump also touches docker-tag group** (README.md ~81/~380, docs/INSTALLATION.md 7+ tags,
+  docker-compose.yml:1).
+- **Do NOT touch** (independently versioned, would break if "fixed"): `sdk/python/pyproject.toml`
+  (auto-synced by release.yml:352 at publish), `sdk/typescript/package.json` (5.55.0),
+  `loki-ts/package.json` (0.1.0-alpha.1), `vscode-extension/package.json` (deprecated).
+- **FIX in v8 - release-notes bug** (`release.yml:179/231`): awk expects bracketed `## [VERSION]` but
+  CHANGELOG uses unbracketed `## vVERSION`, so release notes have silently been generic. Fix the awk or
+  the header format (one PR, verify the extracted body is non-empty).
+- **Dashboard frontend rebuilt** (`cd dashboard-ui && npm ci && npm run build:all`) - writes both
+  `dashboard-ui/dist/` and `dashboard/static/`.
+- **Pre-publish validation** (CLAUDE.md 3a): `npm pack --dry-run` contains web-app/dist + dashboard/static;
+  fresh global install serves web app + API.
+- **Per-job release verification**: `gh run view <id> --json jobs` per channel (npm/Docker/Homebrew/Release),
+  not just "workflow green".
+- **Post-release smoke from SHIPPED artifacts on BOTH routes**: `npm pack loki-mode@8.0.0` + `bun run bin/loki
+  version` and `LOKI_LEGACY_BASH=1 ... version`; `docker run --rm asklokesh/loki-mode:8.0.0 doctor --json`;
+  WebFetch brew formula version+sha.
+- **Cleanup after every local-ci/validation**: `lsof -ti:57374 | xargs kill -9; rm -rf /tmp/loki-* /tmp/test-* /tmp/package /tmp/*.tgz`.
+
+---
+
+## Do-NOT list (binding)
+
+1. Do NOT replace the 3-reviewer council with a single-LLM outcome-grader. Structured-outputs changes
+   the OUTPUT FORMAT (text->JSON), NOT the 3-judge architecture. That's the moat.
+2. Do NOT add an LLM judge to the bench grader (deterministic exit==0 only; `validate_adapter_output`
+   rejects self-judged keys).
+3. Do NOT trust council APPROVE / completion-claim as the bench pass signal (fake-green failure mode).
+4. Do NOT touch `build_prompt()` output text without founder auth + 60-fixture regen + 60/60 bash<->TS.
+5. Do NOT change corpus/grader/price-table across a before/after pair.
+6. Do NOT run a real engine build from the worktree.
+7. Do NOT add a native flag to one route only (silent runtime divergence past all parity gates).
+8. Do NOT ship a change that doesn't move the bench the right way.
+9. Do NOT rebuild what's already adopted (--effort/--max-budget-usd plumbing, council --json-schema path).
+
+---
+
+## FOUNDER SCOPE DECISIONS (2026-07-13, locked)
+
+- **SCOPE = FULL ARC** including founder-gated items 8 (caching) and 9 (self-heal-from-logs).
+  This constitutes explicit authorization to unlock `build_prompt()`'s 60-fixture byte-lock WHEN
+  those items come up - executed per Deliverable 3 (regenerate all 60 fixtures via `run-bash.sh`,
+  keep bash<->TS 60/60 in the same PR, full council + local-ci). Founder-gated items still run LAST,
+  after all bucket-(a) structured-output wins are banked and bench-measured. Caching (8) still
+  requires the CLI-mechanics verification (does the CLI fold cache_control across per-iteration
+  processes?) BEFORE committing - if it's a no-op, report that and drop it, don't ship a no-op.
+- **BASELINE = 3-SPEC SMOKE FIRST.** Prove the full pipeline (baseline -> one change -> measure ->
+  gate rule) on a tiny 3-spec corpus to validate the harness machinery cheaply, THEN build the real
+  discriminator-derived corpus (simple+hard+multi-failure+token-heavy) and run the full v7.128.2
+  baseline. Catches harness bugs before the big real-dollar run.
+- **Honesty pre-commit stands:** most iteration wins are already shipped; expect single-digit-% to
+  maybe-2x from tuning, NOT 100x (the real 100x is the already-scoped k8s INFRA work, not this arc).
+  Report the true number even if unimpressive.
+
+## Consolidation + sequencing
+
+1. Create branch `feature/rarv-c-100x-primitives`. Build harness, run 3-SPEC SMOKE to validate the
+   pipeline, then commit the full v7.128.2 baseline (Deliverable 1) before any change.
+2. Write `docs/RARV-C-100X-PLAN.md` = this plan (supersedes/links the two prior v7.121.5 docs; keep
+   them as history, note they're superseded).
+3. Execute the adoption table in ranked order, one primitive per commit, bench + full gate after each.
+4. Founder-gated items (8 caching, 9 self-heal build_prompt half) LAST, only after (a)-items banked and
+   explicit unlock.
+5. Release v8.0.0 per Deliverable 5 once the bench shows the aggregate win (or honestly report the real
+   delta if single-digit - the plan pre-commits to reporting the true number, not dressing it up).
+
+## Verification (how to test end-to-end)
+- Bench: `bash benchmarks/bench/run.sh run <spec> --trials 3` from isolated scratch; read
+  iterations/cost/duration from result JSON; grader `exit==0`. 2-spec smoke asserts [pass, fail].
+- Structured-outputs: hermetic Bun integration test with stub judge asserts JSON verdict parsed,
+  no text-regex path hit; + extraction test for the bash side.
+- Parity: `bash scripts/local-ci.sh` green (runs 60-fixture lock + dual-route CLI + flag-parity tests).
+- Per commit: full 3-reviewer council + local-ci, both routes.

package/docs/RARV-C-CHANGE-MAP.md

@@ -1,5 +1,10 @@
 # RARV-C Efficiency Change Map (apply-and-measure, from lever investigation)
 
+> SUPERSEDED by `docs/RARV-C-100X-PLAN.md` (v8.0.0 arc, 2026-07-13). Kept as history.
+> Anchors here are grounded to v7.121.5 and have DRIFTED; use the 100X plan for current
+> file:line. Note: budget/effort (#7) and council --json-schema were adopted AFTER this doc.
+
+
 Both checks resolve cleanly:
 
 **Check 1 (env propagation): CONFIRMED SAFE.** `_base.py:113` does `full_env = dict(os.environ)` then passes it as `env=full_env` to subprocess. The loki adapter (`loki.py:120`) uses `run_env`. So env-prefixing the bench invocation propagates the knob into the loki subprocess, where completion-council.sh:84 reads it at source time. Every `KNOB=x bench run` command in the plan is a real measurement, not a no-op.

package/docs/RARV-C-LOOP-EFFICIENCY-PLAN.md

@@ -1,5 +1,10 @@
 # RARV-C Loop-Efficiency Upgrade Plan (ultracode phase)
 
+> SUPERSEDED by `docs/RARV-C-100X-PLAN.md` (v8.0.0 arc, 2026-07-13). Kept as history.
+> Anchors here are grounded to v7.121.5 and have DRIFTED; use the 100X plan for current
+> file:line and for the native-primitives-already-adopted findings.
+
+
 Architect: synthesis of the six cookbook pattern sets against the current
 Loki RARV-C loop. This is a PLAN, not code. Every proposed change carries a
 constraint bucket and a bench-gate. No benchmark numbers are asserted here --

package/loki-ts/data/code-review-schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loki-mode.dev/schemas/code-review.json",
+  "title": "Loki Code-Review Verdict",
+  "description": "Structured output contract for the 8-gate code-review reviewer (main + Devils-Advocate). Claude Code emits this when invoked with --json-schema (INLINE content, not a path) --output-format json. A python3/TS adapter re-materializes it into the legacy 'VERDICT: X\\nFINDINGS:\\n- [severity] description' text so _classify_verdict, _severity_is_blocking, _count_nonblocking_findings, the mergeability score, the DA arm, and aggregate.json stay byte-identical. verdict is the sole gating token; findings[].severity feeds blocking (Critical/High) and mergeability (Medium/Low) weighting. NOTE: JSON Schema cannot express the cross-field rule 'a Critical/High finding requires verdict FAIL'; the re-materializer enforces it (force-FAIL on any Critical/High finding) so a self-contradictory PASS+Critical can never be waved through as non-blocking.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["verdict", "findings"],
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": ["PASS", "FAIL"],
+      "description": "PASS if no blocking issue; FAIL if a real issue was found. A FAIL with a Critical or High finding blocks the merge; a FAIL with only Medium/Low is a non-blocking dissent. If any finding is Critical or High you MUST set verdict to FAIL."
+    },
+    "findings": {
+      "type": "array",
+      "minItems": 0,
+      "description": "Zero or more issues. Empty array means clean (equivalent to the legacy '- None' bullet).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "description"],
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["Critical", "High", "Medium", "Low"],
+            "description": "Critical/High are blocking; Medium/Low are advisory and feed the mergeability score."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "One-line issue description, ideally ending with (file:line)."
+          }
+        }
+      }
+    }
+  }
+}

package/loki-ts/data/council-v2-schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loki-mode.dev/schemas/council-v2.json",
+  "title": "Loki Council-v2 Reviewer Verdict",
+  "description": "Structured output contract for a council-v2 reviewer (requirements/test/quality/devils-advocate/general). Claude Code emits this when invoked with --json-schema (INLINE content, not a path) --output-format json. The council-v2 dispatch reads structured_output directly; a sed-carve of prose JSON remains the fail-closed fallback. verdict is the gating token; any parse miss defaults to REJECT (the safe direction).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["verdict", "reasoning", "issues"],
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": ["APPROVE", "REJECT"],
+      "description": "APPROVE if the evidence satisfies the requirements for this reviewer's lens; REJECT otherwise."
+    },
+    "reasoning": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "description": "Short justification for the verdict."
+    },
+    "issues": {
+      "type": "array",
+      "minItems": 0,
+      "description": "Zero or more issues found. Empty array is allowed on APPROVE.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "description"],
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"],
+            "description": "Issue severity."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "One-line issue description."
+          }
+        }
+      }
+    }
+  }
+}

package/loki-ts/data/done-recognition-schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loki-mode.dev/schemas/done-recognition.json",
+  "title": "Loki Done-Recognition Verdict",
+  "description": "Structured output contract for the done-recognition gate (is a reused PRD already satisfied by the current codebase?). Claude Code emits this when invoked with --json-schema (INLINE content, not a path) --output-format json. The gate DEFENSIVELY re-derives the verdict from requirements[].status, never trusting the top-line verdict, so a valid requirements array is the load-bearing part. Any parse miss falls back to the existing json.loads/brace-slice path, which defaults to inconclusive (the safe direction).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["verdict", "summary", "requirements"],
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": ["done", "incomplete", "inconclusive"],
+      "description": "Top-line claim. done ONLY when ALL requirements are met AND fresh tests are green; incomplete when any requirement is unmet; inconclusive when ground truth cannot be established. The gate re-derives this from requirements[].status regardless."
+    },
+    "summary": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "One plain sentence for the user."
+    },
+    "tests": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["passed", "total", "green"],
+      "properties": {
+        "passed": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 },
+        "green": { "type": "boolean" }
+      }
+    },
+    "requirements": {
+      "type": "array",
+      "minItems": 0,
+      "description": "One entry per PRD requirement, with its satisfaction status. The gate re-derives the verdict from these statuses.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "status"],
+        "properties": {
+          "id": { "type": "string", "maxLength": 256 },
+          "title": { "type": "string", "minLength": 1, "maxLength": 512 },
+          "status": {
+            "type": "string",
+            "enum": ["met", "unmet", "uncertain"],
+            "description": "met = proven satisfied; unmet = not implemented; uncertain = cannot establish."
+          },
+          "evidence": { "type": "string", "maxLength": 1024 }
+        }
+      }
+    }
+  }
+}