loki-mode 11.3.0 → 11.3.2

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

@@ -1,470 +0,0 @@
-# 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 --
-the harness (Deliverable #1) produces them.
-
-Grounded against v7.121.5 source. Line numbers drift; re-verify with grep
-before editing.
-
----
-
-## 0. The one-line thesis
-
-The competitors' edge is INFRASTRUCTURE, not loop rigor. Our proof /
-never-fake-green RARV-C is the moat. So this plan optimizes the loop's
-EFFICIENCY (cost, wall-clock, iterations-to-completion) and NEVER trades away
-verification rigor. The lever that proves it is a bench that measures the
-moat's OUTPUT (verified pass rate, from a deterministic grader) independently
-of the loop's own self-assessment.
-
----
-
-## 1. The gap split
-
-### 1a. Already-scoped INFRASTRUCTURE (NOT this plan's target)
-
-Yesterday's competitor research (reuse, do not re-run) found the
-Replit/Emergent/Bolt advantage is mostly infrastructure: per-build sandbox
-isolation, snapshot/checkpoint, warm pools, fast provisioning. That work is
-already scoped as #2b / #8b / #10 in
-`autonomi-saas/docs/NEXT-AFTER-2026-07-08.md`.
-
-The entire `sandboxes-production` cookbook maps 1:1 onto that scoped k8s work.
-Treat it as a reference implementation, do NOT re-derive it, and do NOT rank
-it here:
-
-| Cookbook technique | Already-scoped item |
-|---|---|
-| Pod-per-session = blast radius | Per-build isolation (#2b) |
-| Per-session volume + SessionStore mirror (local-first, async, non-fatal) | Snapshot/resume, durability C->A (#10) |
-| Lease + heartbeat + reclaim-on-lapse | dead-run-holds-worker (#14) |
-| Idempotent get-or-create keyed on session id | (implicit in per-build spawn) |
-| Standby warm pool, egress NetworkPolicy, gateway auth, OTel | k8s tier-3 infra |
-
-Their loops are NOT more rigorous (Replit ships zero tests). We are ahead on
-verification. Do not re-architect that lead.
-
-Three `sandboxes-production` techniques are net-new for Loki but are
-SAFETY/HEALING, not cost/speed/iterations, so they are explicitly OUT of this
-plan's ranked list (name them, do not smuggle them in):
-- Two-phase investigate(read-only) -> remediate(write) split for
-  self-heal-from-logs.
-- Narrow-scoped write tools + `PreToolUse` content-validation hooks
-  (block-and-let-agent-adapt).
-- archive-vs-delete + optimistic-concurrency version check on state updates.
-
-### 1b. LOOP EFFICIENCY (THIS plan's target)
-
-Cost, wall-clock, iterations-to-completion, at constant verified-pass-rate.
-The `managed-agents`, `agent-patterns`, and `evals-observability` cookbooks
-target this. Techniques: evaluator-optimizer to converge in fewer passes,
-outcome-grader discipline to stop early when genuinely done, cheaper model
-routing, root-cause-clustered parallel fix-loops, plan-big-execute-small
-coordinator economics.
-
-**Honest caveat up front (ponytail rung 2 -- reuse what exists):** the biggest
-iterations-win is LARGELY ALREADY SHIPPED. The framework already has
-explicit-completion-claim, tunable `COUNCIL_CHECK_INTERVAL`, the tier-aware
-`_council_effective_min_iter` floor (v7.105), and the
-`COUNCIL_STAGNATION_LIMIT` circuit breaker. The cookbook's outcome-grader and
-evaluator-optimizer patterns ARE, structurally, the completion council plus
-findings-injection we already run. So most items below are "TUNE an existing
-knob and let the bench prove the setting," NOT "build a new grader." Proposing
-to build what exists would itself be a fabrication.
-
----
-
-## 2. Deliverable #1: the metric harness (BUILD THIS FIRST)
-
-We cannot claim "least cost / fewer iterations" without measured before/after.
-Founder rule: measurable before/after every commit; an unmeasured claim is a
-fabrication under anti-fake-green. So the harness ships before any loop change.
-
-### 2a. Reuse, do not rebuild (the lazy path is the correct path)
-
-Verified against source: the harness is ~95% already built.
-
-- `benchmarks/bench/` already has the frozen contract (`bench_schema.py`,
-  `SCHEMA_VERSION = "1.0"`), a runner (`runner.py`), a deterministic grader
-  (`success = exit==0`, held-out `acceptance.overlay` copied in AFTER the
-  agent finishes), a loki adapter (`adapters/loki.py`), a price table
-  (`prices.json`), and `loki bench` + `loki bench verify`.
-- `bench_schema.py` ALREADY carries the fields we need: `iterations`
-  (`setdefault("iterations", 0)`), `duration_s`, `cost_usd`, `tokens_in/out`,
-  `cache_read_tokens`, `success` (grader-set).
-- `adapters/loki.py` ALREADY reads iteration count from `.loki` state
-  (`_read_iteration_count`, session.json/autonomy-state.json) and captures
-  `duration_s`.
-- The credibility invariant is ENFORCED in code: `validate_adapter_output()`
-  REJECTS any adapter dict carrying `success/quality/passed/score/verdict`.
-  Only the grader sets outcome. This is exactly the "grade the artifact, never
-  the loop's self-assessment" rule -- already a code invariant, not a
-  convention.
-- `benchmarks/speed-benchmark.sh` ALREADY parses the target's
-  `.loki/events.jsonl` for `act_iterations` and `wall_clock_s` from an
-  ISOLATED source copy (never the worktree).
-
-So Deliverable #1 is NOT a build. It is: lock a corpus, reconcile one metric
-source, baseline, and wire the gate.
-
-### 2b. The four target metrics -> where each comes from
-
-| Metric | Source (already exists) |
-|---|---|
-| verified-pass-rate | grader `success = exit==0` on held-out acceptance -> `success_rate` = n_success/n_trials. NEVER council/`completion_claimed`. |
-| $/build | `cost_usd` per task (adapter tokens x frozen `prices.json`); `cost_usd_per_solved` aggregate already in schema. |
-| iterations-to-completion | `iterations` field, populated by `adapters/loki.py` `_read_iteration_count`. |
-| wall-clock/build | `duration_s` (adapter wall-clock around the subprocess). |
-
-### 2c. The genuine delta (small, concrete)
-
-1. **Reconcile the iterations source (harden, do not duplicate).**
-   `adapters/loki.py` reads `iteration` from `session.json`;
-   `speed-benchmark.sh` parses `events.jsonl`. These CAN disagree. Pick ONE
-   canonical source so both harnesses agree -- prefer the `events.jsonl`
-   `iteration_complete` count (it is the real per-session timeline; session
-   state can be mid-write). Make `adapters/loki.py` read events.jsonl with
-   session.json as fallback. One parser, copied from
-   `speed-benchmark.sh` lines ~119-179. Bucket (a).
-2. **Confirm wall-clock coverage.** `duration_s` already exists; verify it is
-   the full subprocess wall-clock, not per-iteration. If it is, no new field
-   is needed and we avoid touching the frozen schema at all. If a distinct
-   `wall_clock_s` is truly required, it is an ADDITIVE optional field
-   (`setdefault`), but the schema header says "do not change without updating
-   SCHEMA_VERSION and every slice" -- so treat any field add as a
-   SCHEMA_VERSION bump + all-slice update. PREFER reusing `duration_s`.
-3. **Lock the corpus.** 5-15 fixed specs under `benchmarks/bench/tasks/` (or
-   a new `benchmarks/corpus/`), each with machine-checkable held-out
-   acceptance (exit code / http status / file exists / regex). Dev on 2, run
-   on all. `task_hash` (spec + acceptance + model, already computed) is the
-   reproducibility anchor.
-4. **Ship the 2-spec smoke sanity check:** one spec that MUST pass, one
-   deliberately-underspecified that MUST fail; assert
-   `verified_pass == [True, False]`. If the grader cannot tell those apart it
-   measures nothing. This is the single runnable check the harness leaves
-   behind.
-
-### 2d. Reproducibility contract (frozen across every before/after)
-
-- Corpus, grader (acceptance harness), and `prices.json` are FROZEN across a
-  before/after pair. Changing any of them destroys comparability exactly like
-  swapping a grader model would. Adding output fields is safe (`task_hash`
-  covers spec+acceptance+model); changing the corpus is not.
-- Every results file persists `loki_version` + `task_hash` + price-table hash
-  so any past number is reproducible and its config travels with it
-  (`benchmarks/results/<version>-<stamp>.json`, already the pattern).
-- Baseline = N real off-worktree builds = real dollars and hours. Run from an
-  isolated source copy with cwd AND `LOKI_TARGET_DIR` pinned to scratch, per
-  the never-run-from-worktree rule. Per-build try/except + hard timeout: a
-  crashed/hung build scores 0 (fail), never aborts the batch. Retry a build
-  only on infra error (network/rate-limit), NEVER on a real failure.
-
-### 2e. The gate rule (operationalizes anchors 1 + 3)
-
-> A loop-efficiency change SHIPS iff it improves at least one of
-> {iterations-to-completion, $/build, wall-clock} BEYOND THE BASELINE'S NOISE
-> BAND AND does not regress verified-pass-rate, measured on the frozen corpus
-> vs the committed baseline.
-
-No change ships unless the bench moves the right way. That one rule is anchor
-1 (optimize efficiency, never trade the proof-moat) and anchor 3
-(bench-gated, no unmeasured claims) made mechanical.
-
-### 2e-HARDENING (advisor 2026-07-08 - blocking; decided BEFORE any results)
-
-Three holes that make an unhardened bench produce fake-green "wins":
-
-1. **NOISE FLOOR (blocking).** Agentic builds are non-deterministic; iterations
-   /$/wall-clock vary run-to-run. "Improves the right direction" with no variance
-   threshold ships random noise as a win ~half the time. RULE: the baseline
-   reports SPREAD (std dev or min-max across trials), not just means. A change
-   ships only if its metric moves BEYOND the baseline's noise band (mean delta >
-   baseline trial std, or non-overlapping min-max). If an effect is smaller than
-   trial variance at N trials, either raise trials or report "no measurable
-   effect" and DO NOT ship. The noise bar is decided now, not rationalized after.
-2. **RECONCILE-METRICS-FIRST (blocking).** Fix the iterations source (2c.1 ->
-   events.jsonl canonical) BEFORE baselining. Baselining on an ambiguous source
-   (session.json vs events.jsonl disagree) corrupts every iterations before/after.
-   This is a PREREQUISITE step, not parallel.
-3. **CORPUS FROM DISCRIMINATORS (expensive to reverse - frozen at baseline).**
-   Do NOT pick "5-15 representative specs." Derive the corpus BACKWARD from what
-   each ranked change must discriminate:
-   - Rank 2 (tier routing): MUST include HARD specs that must stay on the strong
-     model without pass-rate regression, else the anchor-1 guard (cheap tier must
-     not regress hard builds) is untestable and you ship a silent regression.
-   - Rank 3 (parallel fix-loops): MUST include specs that produce MULTI-CLUSTER
-     failures.
-   - Rank 5 (distilled returns): MUST include TOKEN-HEAVY specs.
-   Mix: simple + hard + multi-failure + token-heavy. Frozen once baselined (2d).
-
-### 2f. Cost envelope + honesty pre-commit
-- Envelope: ~5-10 specs x 3 trials x (1 baseline + ~7 ranked changes) ~= 120-240
-  real builds = real dollars + hours. START SMALL: prove the full pipeline
-  (baseline->one change->measure->gate) on a 3-spec corpus FIRST to validate the
-  machinery mechanically, THEN build the real discriminator-derived corpus and
-  baseline. Grow corpus only if variance demands it.
-- HONESTY PRE-COMMIT: the plan already says most iteration wins are shipped;
-  expect single-digit-% to maybe-2x from tuning, NOT 100x. Pre-commit to reporting
-  the real number even if unimpressive, and to stating plainly: "the loop is
-  near-optimal; the real 100x is the INFRA work (already scoped #2b/#10), not
-  here." Do not let the measurement spend create pressure to dress up a small
-  delta - that would be fake-green.
-
----
-
-## 3. Ranked upgrade list
-
-Ranked by (impact / effort), bucket-(a) first. Every item names its cookbook
-pattern, expected effect, bucket, bench validation, and rough effort.
-
-Bucket key:
-- **(a)** ORCHESTRATION-LEVEL -- changeable now (run.sh model routing, council
-  gating, iteration control constants, sub-invocation that does NOT feed the
-  next prompt). No `build_prompt()` change.
-- **(b)** NEEDS FOUNDER AUTHORIZATION -- requires unlocking `build_prompt()`
-  (60-fixture byte-mirror parity lock).
-- **(c)** NEEDS OFF-WORKTREE REAL-BUILD VALIDATION -- cannot be proven without
-  real builds that must NOT run from the worktree.
-
-Discriminator for (a) vs (b): *does the change alter `build_prompt()` output
-text?* If it changes what text enters the next prompt (findings, rubric,
-feedback), it is (b). If it only changes WHEN the council convenes, WHICH model
-runs, or a sub-invocation whose output is not concatenated into the next
-prompt, it is (a). Prompt-touching patterns are SPLIT into their (a) and (b)
-halves below -- do not file a whole pattern under one bucket.
-
----
-
-### Rank 1 -- Tune the completion-council convergence knobs
-
-- **Pattern:** outcome-grader "stop early when genuinely done" +
-  evaluator-optimizer "PASS gate stops the loop the moment criteria are met"
-  (`managed-agents`, `agent-patterns`). We already HAVE the grader (the
-  council). This item TUNES it, does not build it.
-- **Concrete:** sweep `COUNCIL_CHECK_INTERVAL` (default 5,
-  `completion-council.sh:84`), `_council_effective_min_iter`
-  (`:3555`), and `COUNCIL_STAGNATION_LIMIT` (default 5, `:132`) on the corpus;
-  pick the settings that cut iterations-to-completion without regressing
-  verified-pass-rate. Also verify the explicit-completion-claim fast path
-  (`:3601`) fires on the corpus (the v7.105 lever: a done-at-1 build should
-  stop near iter 1, not grind to the next interval).
-- **Effect:** fewer wasted idle iterations -> lower $/build + wall-clock.
-  Largest iterations lever that is NOT already maxed.
-- **Bucket:** (a). Constants + gating only; no prompt text.
-- **Bench validation:** iterations + $/build must drop, verified-pass-rate
-  flat. If pass-rate drops, the interval is too aggressive -- revert.
-- **Effort:** LOW (constant sweep + bench runs). Cost is the real-build $.
-
-### Rank 2 -- Model-tier routing by task complexity
-
-- **Pattern:** Routing (`agent-patterns`) -- a cheap classifier routes easy
-  inputs to the cheap model, hard ones to the strong model; plan-big-
-  execute-small coordinator economics (`managed-agents`).
-- **Concrete:** `LOKI_SESSION_MODEL` is the single largest cost lever
-  (`run.sh:16932`) and today it is one pinned tier for the whole run. Wire
-  `detect_complexity()` (`run.sh:1338`) -> session tier so simple specs pin
-  cheaper (haiku/sonnet) and complex specs pin higher, instead of a flat
-  default. Keep it a unified intelligent default (opt-out knob), never a
-  fragmented set of flags.
-- **Effect:** direct $/build reduction on the simple-spec majority; strong
-  model reserved for the hard tail. Dominant cost lever.
-- **Bucket:** (a). Model selection, no prompt text.
-- **Bench validation:** $/build drops on simple-spec corpus members,
-  verified-pass-rate flat across ALL members (guard: cheaper tier must not
-  regress pass on the hard ones -- that is the anchor-1 trap).
-- **Effort:** LOW-MED. `detect_complexity` already exists; wire it to the tier
-  map and gate on the bench.
-
-### Rank 3 -- Root-cause-clustered parallel fix-loops
-
-- **Pattern:** iterate-fix-failing-tests + "cluster before you parallelize"
-  (`managed-agents`); Parallelization for independent slices
-  (`agent-patterns`).
-- **Concrete:** on a code-review/test BLOCK, bucket failures by root module
-  and fan out ONE fix-worker per INDEPENDENT cluster (worktree per cluster),
-  then re-run the WHOLE suite once at merge as the independent verify. Do NOT
-  fan out per-test -- failures share root causes, per-test workers duplicate
-  the same fix and conflict (the cookbook's own `test_mean` caveat).
-- **Effect:** wall-clock collapse on multi-cluster failures (parallel vs
-  serial); fewer iterations via root-cause (not symptom) fixes.
-- **Bucket:** (a) for the orchestration (fan-out + merge + whole-suite
-  re-verify happen in run.sh / fleet, no prompt-text change). (c) for
-  proving it -- parallel worktree fix-loops must be validated off-worktree on
-  real multi-failure builds.
-- **Bench validation:** wall-clock drops on corpus members that produce
-  multi-cluster failures; verified-pass-rate flat (the merge whole-suite
-  re-run is the non-negotiable guard against over-fix/regression).
-- **Effort:** MED. Clustering heuristic + worktree fan-out + merge verify.
-
-### Rank 4 -- Per-role tool-scoping in the SDLC fleet
-
-- **Pattern:** coordinate-specialist-team "narrowest tool allowlist per role"
-  (`managed-agents`); tool descriptions drive behavior.
-- **Concrete:** give each fleet role (architect, dev, SDET, reviewer) the
-  minimal allowed-tools list it needs (reviewer: read-only; researcher:
-  web+read only). Claude and Codex both support per-invocation tool
-  restriction -- provider-agnostic.
-- **Effect:** fewer wrong-turn iterations (a reviewer cannot wander into
-  bash); smaller blast radius. Iterations lever, modest.
-- **Bucket:** (a). Invocation tool lists, no prompt text.
-- **Bench validation:** iterations flat-or-down, verified-pass-rate flat. This
-  one mostly de-risks; expect small bench movement. If the bench does not
-  move, ship only if it reduces wrong-turn incidents in the transcript
-  (secondary signal), else defer (ponytail: do not ship a no-op).
-- **Effort:** LOW.
-
-### Rank 5 -- Structured distilled-return contract for workers (coordinator economics)
-
-- **Pattern:** plan-big-execute-small "workers return DISTILLED summaries, not
-  raw material" + XML/JSON structured handoff (`managed-agents`,
-  `agent-patterns`).
-- **Concrete:** enforce that fleet workers return a small structured payload
-  (JSON) up to the coordinator, never dump raw file/log/page content back up
-  the chain. Keeps the coordinator context small -> cheaper, sharper
-  synthesis. Gate the fan-out on a granularity heuristic (only shard genuinely
-  token-heavy INDEPENDENT slices; the cookbook warns over-sharding RAISES the
-  bill and narrow tasks do not pay).
-- **Effect:** $/build reduction on token-heavy multi-worker builds; guards
-  against the degenerate "one frontier round-trip for nothing" case.
-- **Bucket:** (a) for the worker return contract and fan-out granularity
-  gate (fleet orchestration). NOTE: if the distilled summaries are
-  concatenated into the NEXT `build_prompt()` iteration, that concatenation
-  path is (b) -- keep the contract change on the worker->coordinator hop, not
-  the coordinator->next-prompt hop, to stay in (a).
-- **Bench validation:** $/build drops on token-heavy corpus members;
-  verified-pass-rate flat (guard: distillation must not summarize away
-  nuance the grader checks).
-- **Effort:** MED.
-
-### Rank 6 -- Confidence-calibrated escalation lane (already partly shipped)
-
-- **Pattern:** gate-human-in-the-loop decide/escalate calibration
-  (`managed-agents`).
-- **Concrete:** the uncertainty-gated escalation is already default-on
-  (`run.sh:18236`). This item TUNES the confidence threshold so the confident
-  majority stays in the fast/cheap autonomous lane and only the genuinely
-  low-confidence + unsafe tail escalates/handoffs (never fake-greens, never
-  blocks-to-ask -- honors the no-human-in-loop runtime rule). Route the
-  low-confidence tail to a stronger model rather than a human where the action
-  is reversible.
-- **Effect:** avoids MAX_ITERATIONS burn on stuck loops (caps wasted
-  iterations); reserves expensive lane for the tail.
-- **Bucket:** (a). Threshold + routing, no prompt text.
-- **Bench validation:** iterations drop on corpus members that currently
-  thrash toward the cap; verified-pass-rate flat.
-- **Effort:** LOW.
-
-### Rank 7 -- Enriched findings-injection text (FOUNDER-GATED)
-
-- **Pattern:** evaluator-optimizer "feed specific feedback + prior attempts
-  back to the generator" + outcome-grader rubric discipline
-  (`agent-patterns`, `managed-agents`). This is our highest-leverage
-  iterations lever AND the most likely to be byte-locked.
-- **Concrete:** `LOKI_INJECT_FINDINGS` already injects structured per-finding
-  records into the next prompt (default-on). ENRICHING that injected TEXT
-  (better-targeted, rubric-shaped, one-bullet-per-failure format) would make
-  each retry more directed and converge in fewer passes. BUT the injected text
-  flows through `build_prompt()`, whose output is pinned by the 60-fixture
-  SHA-256 parity lock (`loki-ts/tests/parity/build_prompt.test.ts`,
-  `loki-ts/src/runner/build_prompt.ts`, gold under
-  `loki-ts/tests/fixtures/build_prompt/`).
-- **Split (per anchor 2):**
-  - (a) part: tuning WHEN findings are injected / WHICH findings are selected
-    (selection logic upstream of the prompt) -- changeable now if it does not
-    alter the emitted text bytes.
-  - (b) part: changing the injected TEXT / format / rubric wording -- requires
-    founder authorization to unlock the byte-lock, then regenerate all 60
-    fixtures via `run-bash.sh` and keep bash<->TS parity 60/60.
-- **Effect:** fewer iterations-to-completion (directed retries). Potentially
-  large, but gated.
-- **Bucket:** (b) for the text change; (a) for the selection-logic half.
-- **Bench validation:** iterations drop, verified-pass-rate flat-or-up. Prove
-  off-worktree (hermetic Bun integration test with stub judge, then real
-  builds).
-- **Effort:** MED code + HIGH process (founder unlock + fixture regen +
-  full council + local-ci). Do NOT start the (b) half without authorization.
-
----
-
-## 4. Sequencing for the ultracode phase
-
-1. **Deliverable #1 first: lock the harness + baseline.** Reconcile the
-   iterations source (2c.1), confirm wall-clock coverage (2c.2), lock the 5-15
-   spec corpus (2c.3), ship the 2-spec smoke check (2c.4), then run the
-   baseline: N real off-worktree builds -> committed
-   `benchmarks/results/<baseline>.json`. Nothing else ships until this exists.
-2. **Bucket-(a) wins, ranked, each bench-gated.** In order: Rank 1 (council
-   knob sweep) -> Rank 2 (complexity->tier routing) -> Rank 6 (escalation
-   threshold) -> Rank 4 (per-role tool scoping) -> Rank 3 orchestration half
-   -> Rank 5 worker-return contract. Each one: change, re-run corpus, apply
-   the gate rule (2e). If the bench does not move the right way, do not ship
-   it (ponytail: no no-ops).
-3. **Bucket-(c) validation for anything needing real parallel builds** (Rank 3
-   fix-loop fan-out): prove off-worktree on real multi-failure builds before
-   shipping.
-4. **Founder-gated items LAST.** Rank 7 (b) half only after: (i) bucket-(a)
-   wins are banked and measured, (ii) explicit founder authorization to unlock
-   `build_prompt()`, (iii) fixture regen + 60/60 parity + full 3-reviewer
-   council + local-ci green. Do the (a) selection-logic half of Rank 7 in
-   step 2 if it stands alone.
-5. **Every ship:** full gate is back (Wednesday 2026-07-08, the 1-week
-   relaxation has expired). Runtime/council changes = full 3-reviewer council
-   (2 Opus + 1 Sonnet, unanimous APPROVE, loop to 3/3) + `local-ci.sh` green +
-   watch all GH workflows. Prove RARV-C changes with hermetic Bun integration
-   tests (stub judge, `LOKI_OVERRIDE_REAL_JUDGE=0`, mkdtemp scratch, no token
-   cost) -- pattern already established in
-   `loki-ts/tests/integration/override_on_block.test.ts`.
-
----
-
-## 5. Explicit "do NOT do" list
-
-Tempting things that re-architect the moat, hit the byte-lock, or fabricate
-numbers:
-
-1. **Do NOT replace the completion council with a single-LLM outcome-grader.**
-   That kills the 3-reviewer rigor moat -- the exact thing we are ahead on.
-   Lift the rubric DISCIPLINE (checkable criteria, evidence-earned pass,
-   one-bullet-per-failure feedback, same-gap non-convergence detection), NOT
-   the single-judge architecture.
-2. **Do NOT add an LLM-judge to the bench grader.** The grader is
-   deterministic (`success = exit==0` on held-out acceptance) and the
-   credibility invariant is enforced in code
-   (`validate_adapter_output` rejects any self-judged key). An LLM judge is a
-   second thing you must hold fixed and it breaks the invariant. Specs are
-   code -- acceptance is machine-checkable for free.
-3. **Do NOT trust `completion_claimed` / council APPROVE as the bench pass
-   signal.** That is grading the loop's self-assessment -- the fake-green
-   failure mode. Pass = independent deterministic acceptance only.
-4. **Do NOT touch `build_prompt()` output text without founder authorization.**
-   60-fixture SHA-256 byte-mirror parity lock. Any text change = regenerate
-   gold + keep bash<->TS 60/60 or CI (`parity-drift`) fails. This gates
-   Rank 7's (b) half.
-5. **Do NOT change the corpus, grader, or price table across a before/after
-   pair.** Comparability dies; the number becomes a fabrication. Additive
-   output fields are safe; corpus churn is not.
-6. **Do NOT cite the cookbook's headline numbers as ours.** "~2.5x cheaper /
-   ~3x faster" (plan-big-execute-small) and "84-98% billed at worker rate" are
-   THEIR task on THEIR corpus. Our numbers come from our harness, later.
-7. **Do NOT over-shard plan-big-execute-small or fan fix-workers per-test.**
-   The cookbook's own caveats: over-sharding RAISES the bill (delegation floor
-   cost), narrow tasks do not pay, and per-test workers duplicate shared-root
-   fixes and conflict. Cluster by root cause first, then parallelize across
-   clusters.
-8. **Do NOT run a real engine build from the worktree to validate any of
-   this.** TARGET_DIR resolves onto the worktree and self-mutates it. Baseline
-   and all (c) validation run from an isolated source copy with cwd +
-   `LOKI_TARGET_DIR` pinned to scratch (the speed-benchmark.sh discipline).
-9. **Do NOT re-scope the sandboxes-production infra work here.** It is already
-   #2b/#8b/#10 in autonomi-saas. Reference the cookbook as an impl, do not
-   re-derive or re-rank it.
-10. **Do NOT ship a change that does not move the bench the right way.** The
-    gate rule (2e) is binding: improve >=1 of {iterations, $/build,
-    wall-clock} AND no verified-pass-rate regression, or it does not ship.

package/docs/SHAREABLE-PROOF-PLAN.md

@@ -1,194 +0,0 @@
-# Shareable Proof-of-Run: Implementation Plan (v7.19.3)
-
-Architect plan for adding opt-in shareability to the proof-of-run artifact
-without breaking the v7.18.2 zero-egress posture. Design only.
-
-## 1. Verified current state
-
-All claims read from source.
-
-**Generator** `autonomy/lib/proof-generator.py` (689 lines)
-- `_build_proof` (line 366) assembles the frozen schema v1.0 dict. `deployment`
-  set at line 401: `{"deployed_url": deployed_url, "public_url": None}`.
-  `public_url` is ALWAYS `None` at generate time. This is the publish-time
-  injection slot the design hangs on.
-- `_build_social_hook` (line 444) computes the one-line hook from already-redacted
-  fields only: `cost.usd` via `_fmt_usd_hook` (line 427), `files_changed.count`,
-  and council ratio via `_council_ratio` (line 406). Cost clause omitted when usd
-  is None (never fabricates `$0.00`).
-- `_render_html` (line 562) loads `proof-template.html`, replaces
-  `__PROOF_OG_DESCRIPTION__` (og + twitter metas) with `_attr_esc(hook)`, then
-  replaces `__PROOF_JSON__` (escaping `<` as `<`). Falls back to
-  `_render_fallback_html` (line 470) when template missing.
-- CHOKEPOINT: `generate` (line 582) calls `proof_redact.redact_tree(proof)` once
-  (line 609), refuses to emit if redaction did not run (line 613), applies length
-  caps AFTER redaction (line 619), then hashes and writes proof.json + index.html.
-
-**Template** `autonomy/lib/proof-template.html` (803 lines)
-- Self-contained / zero-egress by contract (header comment lines 1-40). Social
-  meta lines 46-55: og:title, og:description, twitter:card=summary,
-  twitter:description. Line 46: "No og:image (would break self-containment)" -
-  preserved by this plan.
-- Hero markup lines 261-265 (`.hero`, `#heroLine`, `#heroSub`, `#heroActions`);
-  `.hero-actions`/`.btn` CSS at 105-115. `renderHero` (line 426) builds the hero
-  client-side. `renderCta` (line 732) emits command blocks with `data-copy`.
-- `wireCopy` (line 762) is a delegated click handler keying off `data-copy`,
-  using `navigator.clipboard` with `execCommand` fallback. PATTERN to mirror for
-  share buttons + copy-link.
-- Template reads `deployment.public_url` at line 466 (`renderTier1`).
-
-**CLI** `autonomy/loki`
-- `cmd_proof` (line 26277): list/show/open/share. `share` (26393) gates
-  `--hosted` to `_loki_hosted_publish_proof` (26113, posts redacted bytes to
-  `LOKI_HOSTED_ENDPOINT`, honest "no backend yet" otherwise), else uploads
-  index.html AS-IS to a gist via `_loki_gist_upload` (26021, `gh gist create`,
-  exposes `LOKI_LAST_GIST_URL`). The default gist path never fills public_url or
-  re-renders.
-- Social hook is reimplemented inline in Python at 26503-26553 (duplicates
-  `_build_social_hook`). This plan adds no third copy.
-
-**Dashboard** `dashboard/server.py`: `_proofs_dir` (7668), `_safe_proof_run_dir`
-(7672, realpath-contained), `GET /api/proofs` (7689). Read-only consumer;
-untouched.
-
-**Redaction** `autonomy/lib/proof_redact.py`: `redact_tree` (266),
-`redact_value` (260), `set_context`/`reset_context` (37/51), `RULES_VERSION =
-"1.0"` (29). Reused, never reinvented.
-
-**Existing tests**: `tests/test_proof_html.py` (`test_no_external_resource_refs`
-forbids `src=`, `@import`, `url(http`, any non-allowlisted `https?://`; allowlist
-only `github.com/asklokesh/loki-mode`; plus null-cost-never-renders-$0.00),
-`tests/test_proof_redaction.py` (secret-class + e2e), `tests/cli/test-proof-command.sh`,
-`tests/dashboard/test_proofs_routes.py`.
-
-**Dependency posture**: no Pillow/cairo/cairosvg. Local PNG rasterization would
-add a dependency and break the zero-dep local posture - ruled out.
-
-## 2. The og:image decision
-
-CHOSEN: keep the local proof zero-egress with NO og:image; add a branded in-page
-card rendered from the redacted dict; inject og:image and share-target URLs ONLY
-at publish time via the existing `deployment.public_url` slot, on an
-HTML-serving host.
-
-- Option (a) data-URI og:image: REJECTED. og:image is spec'd as a URL; scrapers
-  do not reliably honor data-URI og:image. Bloat for zero benefit.
-- Option (b) separate card file referenced only at publish: PARTIALLY ADOPTED. A
-  real og:image needs a public URL, absent at generate time. Reference no image
-  at generate; at publish (only if the proof reaches an HTML-serving host
-  returning a public URL) that host is where og:image is set.
-- Option (c) branded in-page card: ADOPTED as the always-on self-contained
-  visual. Inline CSS / inline SVG, rendered client-side from the redacted dict.
-  Zero egress, zero new deps, redaction-safe.
-
-HONEST GIST LIMITATION: `loki proof share <id>` publishes to a GitHub Gist. The
-gist page serves GitHub's own og tags (profile picture), not the uploaded HTML's
-og tags; `raw.githubusercontent.com` serves `text/plain`, not scraped. So the
-gist path does NOT produce a rich preview of the proof card. Only an
-HTML-serving host returning a real public URL served as `text/html` (the
-`LOKI_HOSTED_ENDPOINT` seam) can. Stated plainly in docs + CLI output.
-
-UNIFYING INSIGHT: og:image, share-button `url=`, and copy-link all need a public
-URL absent at `file://` generate time. All three key off
-`deployment.public_url`: null at generate (share degrades to text-only/hidden),
-populated at publish.
-
-## 3. Disjoint dev slices
-
-Binding constraints (every slice): no VERSION bump; no commits; no emojis; no em
-or en dashes (ASCII hyphen only); no new runtime dependencies; the default
-generate path stays byte-for-byte zero network calls.
-
-**Slice A - Template: branded card + JS-click share buttons**
-(`autonomy/lib/proof-template.html` only)
-- Style the hero (261-265) into a branded card: what was built (files_changed +
-  spec source), verified (council verdict/ratio + gates), cost (cost.usd),
-  duration (wall_clock_sec), plus Loki/Autonomi branding. Inline CSS / inline SVG.
-  Rendered by `renderHero` from the redacted dict; no new schema fields.
-- Add a share row in `.hero-actions` using `data-share` attributes (mirror
-  `data-copy`): X/Twitter, LinkedIn, Copy link. NO literal `https://` href in
-  static HTML (keeps `test_no_external_resource_refs` green). A new delegated
-  handler assembles the intent URL at click time:
-  - X: `https://twitter.com/intent/tweet?text=<hook>&url=<public_url>` (hook from
-    og:description meta; public_url from parsed proof).
-  - LinkedIn: `https://www.linkedin.com/sharing/share-offsite/?url=<public_url>`
-    (URL only; LinkedIn ignores prefilled text).
-  - Copy link: writes public_url via the clipboard path wireCopy uses.
-- When public_url is null (default local case): share buttons hide or fall back
-  to copy-the-hook-text; never emit a broken `url=`.
-- og:image meta only as empty/absent default; populated by the publish path.
-
-**Slice B - Generator: hook plumbing + public_url passthrough**
-(`autonomy/lib/proof-generator.py` only)
-- Add `LOKI_PROOF_SHARE_BUTTONS` (default ON; justified below) conditionally
-  including the share-row markers. Reuse `_build_social_hook`.
-- public_url stays None at generate. Optional `LOKI_PROOF_PUBLIC_URL` env, when
-  set, threads into deployment.public_url BEFORE the redaction chokepoint.
-  Default None. No og:image here. No network calls.
-
-**Slice C - CLI: publish-time re-render + og:image/public_url injection**
-(`autonomy/loki` only; OWNS the re-render)
-- Hosted path (`_loki_hosted_publish_proof`, 26113): after the host returns a
-  public URL, re-render with deployment.public_url set + og:image set to the
-  host-minted card URL, then upload. Re-render reuses the generator (env var) so
-  redaction runs again over the URL-injected dict - never a hand-built body.
-- Gist path: byte-for-byte unchanged EXCEPT one honest stdout note (gist previews
-  show GitHub's og tags, not the proof card; point to --hosted). Do not fabricate
-  a public_url for gist.
-
-**Slice D - Docs** (this file + a short note in proof docs / wiki): zero-egress
-invariant, opt-in publish path, gist-vs-hosted preview reality, LinkedIn text
-limitation.
-
-Recommended parallelism: A, B, D in parallel; C after B's flag contract is
-agreed.
-
-## 4. Test plan
-
-Model on `tests/test_proof_html.py`, `tests/test_proof_redaction.py`.
-
-1. Default generate path zero-egress: extend `test_no_external_resource_refs` -
-   generate with share buttons ON, assert NO `src=`, no `@import`, no `url(http`,
-   no `https?://` URL except the github.com/asklokesh/loki-mode allowlist. The
-   load-bearing guard that the JS-click design adds no literal share URLs.
-2. Redaction holds on card + share text: reuse the e2e pattern - plant secrets in
-   council summaries / spec / diffs, generate, assert none survive anywhere in
-   index.html incl. card markup + og:description. Card renders ONLY redacted
-   fields.
-3. Share button URLs well-formed + prefilled: unit-test the JS URL assembly -
-   given public_url, X intent contains URL-encoded hook + url=<public_url>;
-   LinkedIn contains url=<public_url> no text; copy-link copies public_url. Null
-   public_url -> no malformed url=.
-4. og:image populated ONLY on publish: default page has no og:image; simulate
-   hosted re-render with a public URL, assert og:image + public_url populated and
-   re-redacted; gist path leaves page unchanged + prints the note.
-5. Null-cost credibility preserved: card never shows `$0.00` when cost uncollected.
-
-## 5. Honest limits
-
-- Data-URI og:image not reliably scraped (og:image is spec'd as a URL); not used.
-- GitHub gist yields no rich preview of the proof card (gist page = GitHub og
-  tags; raw = text/plain).
-- A rich social preview requires an HTML-serving host returning a public URL (the
-  LOKI_HOSTED_ENDPOINT seam or any static HTML host the user configures). No
-  official Loki hosted backend yet; the seam is honest about this.
-- LinkedIn share ignores prefilled text; it scrapes the destination og tags, so
-  LinkedIn previews depend on the hosted og:image. X intent carries the hook.
-- Sharing is manual / opt-in: a button is inert until clicked; no auto egress.
-- No hosted gallery / discovery feed in this release.
-
-Share-buttons default ON: with JS-click construction there is no literal external
-URL in the static page and no network call until the user clicks. The buttons are
-inert markup until acted on, so they cannot violate the default zero-egress
-invariant. Default ON maximizes the word-of-mouth lever at zero cost to the
-posture; `LOKI_PROOF_SHARE_BUTTONS=0` opts out.
-
-## Zero-egress invariant (precise)
-
-- STAYS zero-egress (byte-for-byte zero network calls): generating a proof and
-  opening the local index.html. No og:image, no src=, no @import, no web fonts,
-  no literal share URLs. Card + hook render from the embedded redacted JSON.
-  Share buttons present but inert.
-- OPT-IN egress (only on explicit user action): clicking a share button, copying
-  the link, and `loki proof share <id>` / `--hosted`. og:image and
-  deployment.public_url are populated only on the hosted publish re-render.