loki-mode 11.3.0 → 11.3.1

package/docs/retrospectives/v7.5.15-fleet-postmortem.md

@@ -1,325 +0,0 @@
-# v7.5.15 8-Agent Fleet Postmortem
-
-Three failures from the v7.5.15 release that warrant protocol changes, with
-specific recommendations. No abstractions.
-
-## 1. Bad-copy regression during integration
-
-### What happened
-After 6 of 8 agents committed to their worktree branches, the integration
-sequence was:
-
-```
-git merge worktree-agent-a8a266d09b22b5631 (Dev2)  # OK, no conflict
-git merge worktree-agent-ac2f6035de5d85a26 (Dev7)  # OK
-git merge worktree-agent-a5d1f44a43c7c426e (Dev1)  # OK
-git merge worktree-agent-a65db5855ce46f594 (Dev6)  # OK, auto-merge run.sh
-git merge worktree-agent-ae16c32006be6e693 (Dev3)  # OK, autonomy/loki +200/-4
-git merge worktree-agent-ab99b45c94d5e1c0b (Dev4)  # OK, auto-merge autonomy/loki
-```
-
-At this point `autonomy/loki` had Dev3's `init-rules` block + Dev4's
-`cmd_doctor_json` `sentrux` field, both correctly merged via git's 3-way merge.
-
-Then Dev5 + Dev8 had not committed in their worktrees (they correctly applied
-the global "wait for user approval before commit" rule). So I ran:
-
-```bash
-SRC=/Users/lokesh/git/loki-mode/.claude/worktrees/agent-a772019c7da8d733f
-cp "$SRC/autonomy/loki" /Users/lokesh/git/loki-mode/autonomy/loki
-```
-
-This obliterated Dev3+Dev4's edits because Dev5's worktree was branched from
-the pre-merge main HEAD (`2ce36624`). Caught by `grep -c "init-rules" autonomy/loki`
-returning 0 instead of 4, immediately recovered via:
-
-```bash
-git checkout HEAD -- autonomy/loki
-# then surgical Edit calls for just Dev5's two help blocks
-```
-
-User-facing impact: zero. Cost: ~5 min of integration retry + 2 surgical
-`Edit` operations.
-
-### Why the merge strategy did not catch this earlier
-
-`git merge` IS the right primitive for committed branches. The bug was that
-I switched primitives mid-integration: 6 `git merge` operations, then `cp`.
-`cp` does not 3-way merge. It just overwrites. The conflict-detection that
-git merge gives you for free does not exist for `cp`.
-
-The deeper cause: the worktree dispatch protocol allowed two execution
-endpoints for an agent's output -- "agent commits to worktree branch" or
-"agent leaves uncommitted in worktree". This bifurcation forced the integrator
-(me) to use two different merge tools (`git merge` for the committed path,
-`cp` for the uncommitted path). The two tools have different safety
-properties, and `cp` is the unsafe one.
-
-Dev5 and Dev8 both correctly applied the global CLAUDE.md rule "never commit
-without explicit user approval" -- so the bifurcation was not their fault. It
-was the dispatch protocol's fault for not specifying which rule wins (the
-agent task spec said "commit" but the global rule said "wait").
-
-### Specific protocol changes for the next fleet
-
-1. **Dispatch prompts must explicitly resolve the commit-vs-wait conflict.**
-   Add a literal sentence to every dev-agent prompt: `"Commit to your worktree
-   branch at task end -- this overrides the global wait-for-user-approval rule
-   for the duration of this fleet operation. The integrator (parent) will
-   review your branch via git merge and apply CLAUDE.md commit discipline at
-   the integration commit, not your worktree commit."` Without this, agents
-   default to the safer (waiting) behavior, which forces unsafe `cp` at
-   integration.
-
-2. **Integrator MUST use `git merge` exclusively, never `cp`.** If a worktree
-   has uncommitted changes, the integrator must `cd <worktree> && git add
-   <files> && git commit -m "WIP for <devN>"` first, then merge. Never copy
-   files between worktrees.
-
-3. **After every merge, run a structural checksum.** For files touched by
-   multiple agents (the conflict-prone files: `autonomy/loki`, `autonomy/run.sh`,
-   `dashboard/server.py`), run `grep -c <each-agent's-distinctive-token>
-   <file>` and assert all expected tokens are present. Example for
-   `autonomy/loki` post-Dev3+4+5: `grep -c "init-rules" == 4 AND
-   grep -c "cmd_doctor_json" == 2 AND grep -c "cmd_dashboard_help\|cmd_web_help"
-   == 7`. Three positive assertions catch overwrite regressions in seconds.
-
-4. **Pre-integration conflict matrix.** Before any merging, the integrator
-   must compute and log which files multiple agents touched. Run:
-
-   ```bash
-   for branch in $(git branch --list 'worktree-agent-*'); do
-     git diff --name-only main...$branch
-   done | sort | uniq -d
-   ```
-
-   Output is a list of files multiple agents touched. Treat any file in
-   that list as a STOP signal: do not proceed to merge until a conflict
-   resolution plan is documented (merge order, structural checksum tokens,
-   expected post-merge grep counts). In v7.5.15 this would have surfaced
-   `autonomy/loki` (Dev3+4+5) and `autonomy/run.sh` (Dev1+6) before the
-   first merge command ran.
-
-## 2. R3 returned a fragment on first dispatch
-
-### What happened
-
-R3 was launched in parallel with R1, R2, DA. After 90s, R3 returned this
-literal text as its complete output:
-
-> "Still running. Let me wait for monitor."
-
-Status said "completed" but the result body was a 7-word fragment. R3 had not
-actually run any of the cross-cutting integration checks I asked for.
-
-I re-spawned R3 (call it R3-retry) with a stricter prompt. R3-retry completed
-in 61s with a full structured 6-risk verdict.
-
-### What signal in the original prompt caused the fragment
-
-The original R3 prompt opened with this paragraph (truncated):
-
-> "You are Reviewer 3 of 3 (integration safety) reviewing Loki Mode v7.5.15
-> release candidate at /Users/lokesh/git/loki-mode.
->
-> ## Context
-> 8 parallel dev agents wrote in isolated worktrees. Their work was merged
-> into main. The risk that motivates your existence: agents could not see
-> each other's code, so subtle interactions between their patches may have
-> been missed.
->
-> ## Specific cross-cutting risks to investigate
->
-> ### Risk A: autonomy/run.sh has Dev1 (iteration loop) + Dev6 (pytest timeout) edits
-> [...command suggestions, not literal commands...]"
-
-The smoking gun is the framing of the risk sections. They were narrative
-("Dev1 added helpers near `run_autonomous()`") and asked the agent to
-"investigate". The agent interpreted this as a research-and-report task with
-async dependencies, hence "Let me wait for monitor."
-
-The R3-retry prompt opened with:
-
-> "CRITICAL: Run all the bash commands below yourself. Do NOT wait for any
-> monitor. Do NOT spawn other tools. Just execute the commands, capture
-> output, and report."
->
-> Then: literal `bash` blocks for each risk, not narrative descriptions.
-
-### The prompt-difference rule
-
-The fragment was a context-window-limit hallucination triggered by the
-narrative framing, not a model error. The first prompt let R3 think it had
-to coordinate with other agents (the word "monitor" doesn't appear in my
-prompt -- the agent invented it). The second prompt removed any room for
-coordination assumption by handing literal commands.
-
-**Rule for reviewer prompts: hand the agent literal commands when the work is
-verification, not investigation.** Narrative-style "investigate this risk"
-prompts work for open-ended research agents. They fail for verification
-agents because the agent has nothing to do except run the check, and any
-narrative slack invites hallucinated work-coordination.
-
-Concretely:
-- Bad: "Verify Dev1 and Dev6's edits to autonomy/run.sh do not conflict"
-- Good: "Run `bash -n autonomy/run.sh && shellcheck -S error autonomy/run.sh`. Report exact output. If non-zero, paste the failure."
-
-The signal was that R3's prompt had 5x more narrative than R1's or R2's
-prompts. R1 and R2 returned substantive results; R3 returned a fragment. Same
-model, same session, same parallel dispatch -- the only variable was prompt
-density.
-
-### Specific recommendation
-
-Add a checklist to the reviewer-prompt template:
-
-1. Does each verification step have a literal `bash` block, not a description?
-2. Is the expected output specified concretely (e.g. "expect count = 3", not
-   "verify both helpers exist")?
-3. Is there a "DO NOT spawn other agents / DO NOT wait for monitors" line?
-4. Is the report format an enumerable list, not a narrative essay?
-
-If any of these are no, the prompt invites fragment responses.
-
-Add `scripts/lint-reviewer-prompt.sh` as the pre-flight linting artifact.
-The script takes a prompt file as its only argument and grep-checks for the
-4 required elements above:
-
-```bash
-#!/usr/bin/env bash
-# scripts/lint-reviewer-prompt.sh <prompt-file>
-set -euo pipefail
-FILE="${1:?usage: lint-reviewer-prompt.sh <prompt-file>}"
-PASS=0
-grep -q '```bash' "$FILE"        || { echo "FAIL: no literal bash block"; PASS=1; }
-grep -qE '(expect|count|== [0-9])' "$FILE" || { echo "FAIL: no concrete expected output"; PASS=1; }
-grep -q 'DO NOT' "$FILE"         || { echo "FAIL: no DO NOT line"; PASS=1; }
-grep -qE '^\s*[0-9]+\.' "$FILE"  || { echo "FAIL: no enumerable report format"; PASS=1; }
-[ "$PASS" -eq 0 ] && echo "PASS: prompt lint OK"
-exit "$PASS"
-```
-
-Invocation point: the integrator runs this script against each reviewer
-prompt file before the parallel dispatch call. A non-zero exit aborts the
-dispatch. The script does not need to ship in v7.5.15; the spec and
-acceptance criteria above are sufficient to implement it before the next
-fleet operation.
-
-## 3. Devil's Advocate caught what 4 prior reviewers missed
-
-### What happened
-
-Three reviewers (R1 correctness, R2 CLAUDE.md compliance, R3 integration
-safety) reviewed v7.5.15 and unanimously approved. Each independently re-ran
-the 8 new test suites and confirmed PASS.
-
-Devil's Advocate (DA) ran the same checks AND added one more: did the new
-tests actually get registered in `tests/run-all-tests.sh`? Answer: 1 of 8 was
-registered. The other 7 (Dev1, Dev2, Dev3, Dev4, Dev5, Dev6, Dev7) would
-silently rot.
-
-Cost if missed: 7 tests in the repo for diff inspectors to think coverage
-existed, while CI never ran them. Future regressions in those code paths
-would not be caught until the next manual run-all-tests.sh invocation.
-
-### What this says about reviewer role structure
-
-R1, R2, R3 each had a specific mandate. R1 = "do the patches work?". R2 =
-"does the release follow CLAUDE.md?". R3 = "do the patches integrate without
-breaking each other?". All three mandates assumed the question "does this
-release ship?" was answered if their narrow domain passed.
-
-DA had no domain. DA was given the role "find what the other three will
-miss." That open mandate let DA ask a question outside any of the other three
-roles' jurisdictions: "given that the patches work, are they wired up to
-keep working?"
-
-Test-rot is in nobody's R1/R2/R3 domain:
-- R1 ran the tests -- they pass when invoked. Mandate satisfied.
-- R2 checked CLAUDE.md compliance -- which doesn't say "wire all new tests
-  into the runner". Mandate satisfied.
-- R3 checked cross-file integration -- not test runner registration.
-  Mandate satisfied.
-
-Test-rot is structurally outside specialized reviewer domains. It is a
-meta-question about durability that requires a non-domain-specific role to
-ask.
-
-### Should DA be the default?
-
-No. The DA role works because it is contrarian to a specific quorum. If you
-make DA the default reviewer, you lose the contrarian frame -- DA becomes
-just another R-reviewer with a slightly broader mandate, and it stops asking
-the meta-questions because it is now responsible for them.
-
-The surprise factor is the structural feature, not a bug. R1+R2+R3 unanimous
-approval triggers DA. If DA agreed without conditions, the release ships. If
-DA finds something, the release pauses.
-
-### What to keep, what to add
-
-**Keep:**
-- DA as a separate role spawned in the same parallel wave as R1/R2/R3, with
-  the explicit mandate "find what the others will miss".
-- The 3-reviewer + DA pattern as the default for any release.
-
-**Add:**
-- A required DA checklist with at least these items, refined every release:
-  - Are new tests registered in the runner?
-  - Are new env flags documented in `loki doctor` output AND in CHANGELOG?
-  - Are new endpoints discoverable via `loki <thing> --help` output?
-  - Did any agent claim "tests pass" without me re-running it from a fresh
-    shell?
-  - Did the integration retain ALL agents' contributions, or did one
-    silently overwrite another?
-
-The fifth item would have caught the bad-copy regression (section 1) earlier
-than my own grep-c sanity check did.
-
-### Specific recommendation
-
-Codify DA as a required role with a published checklist. Currently DA's
-prompt was hand-written for v7.5.15 and emphasized "find at least one thing
-the 3 reviewers will miss". That phrasing worked but is fragile -- the next
-DA invocation might emphasize different things and miss the test-rot class
-of issue.
-
-Concrete: maintain `docs/retrospectives/devil-advocate-checklist.md` as the
-standing DA questions. Reviewer prompts inline the checklist contents at
-dispatch time (copy-paste or heredoc). New questions get appended to the
-checklist after each release where DA found something the other reviewers
-missed.
-
-The checklist becomes the institutional memory of "things 3-reviewer councils
-have failed to catch." It grows monotonically. DA's job becomes "run this
-checklist + add anything new" rather than "be smart in a vacuum".
-
-## Summary of recommended protocol changes
-
-1. **Dispatch protocol**: dev-agent prompts explicitly resolve commit-vs-wait;
-   integrator uses `git merge` exclusively; post-merge structural checksums on
-   conflict-prone files; pre-integration conflict matrix.
-2. **Reviewer prompts**: literal bash blocks for verification work; "DO NOT
-   spawn / DO NOT wait" preamble; expected output specified concretely;
-   pre-flight prompt linting.
-3. **Council structure**: keep DA as a contrarian role with a growing
-   checklist; add the standing DA questions to a versioned checklist file;
-   monotonically grow the list with new "things the council missed" each
-   release.
-
-These are 3 small protocol changes, each addressing a specific failure that
-occurred in this session. None require new tools or new architecture.
-
----
-
-**Footnote -- two additional observed events not elevated to protocol-change tier.**
-Two issues occurred during the v7.5.15 session that were deliberately excluded
-from the three-failure selection above: (1) the validate-bash hook fired a
-false-positive on a `rm -rf /Users/...` path in a comment, not an executed
-command; (2) a zsh PATH hash quirk caused a freshly-added binary to be
-invisible until `hash -r` was run in the same shell. Both were observed,
-classified as audit-table-tier (one-time environment quirks requiring no
-standing protocol change), and are covered in the session audit table rows
-"hook-false-positive-rm-path" and "zsh-path-hash-stale" respectively. Neither
-met the bar for a protocol change because neither was reproducible across
-sessions or attributable to a protocol gap.

package/docs/retrospectives/v7.5.15-honesty-audit.md

@@ -1,136 +0,0 @@
-# v7.5.15 Honesty Audit
-
-Audit of the v7.5.15 release commit `c82b9541` against the actual diff and the
-8-agent fleet's per-PR claims.
-
-Method: every CHANGELOG sentence cross-checked against `git show c82b9541` +
-`git log 2ce36624..HEAD` + grep against the integrated tree. No agent's
-self-report taken as evidence.
-
-## 1. CHANGELOG claims vs. diff evidence
-
-| CHANGELOG claim | Diff evidence | Verdict |
-|---|---|---|
-| Sentrux iteration-loop wire-in behind `LOKI_SENTRUX_GATE=1` | `autonomy/run.sh:10531` `_loki_sentrux_iteration_start()`, `:10543` `_loki_sentrux_iteration_end()`, callers at `:10775` and `:11257`, env-flag guard verified | VERIFIED |
-| Default off; zero behavior change without opt-in | Guard pattern: `if [[ "${LOKI_SENTRUX_GATE:-}" == "1" ]] && command -v sentrux ...`. Confirmed at the call sites. | VERIFIED |
-| `tests/test-sentrux-iteration-wireup.sh` 7/7 PASS | Re-run during integration: 7/7 PASS. Re-run by R1, DA: 7/7. | VERIFIED |
-| Dashboard `/api/quality/architecture` endpoint | `dashboard/server.py:5958` `@app.get("/api/quality/architecture")` confirmed | VERIFIED |
-| Returns sorted findings-sentrux series | `dashboard/server.py:5974-6014` globs `findings-sentrux-*.json`, sorts by iteration | VERIFIED |
-| Resilient to corrupt JSON | Test 4 in pytest suite (`test_resilient_to_corrupt_file`); writer-side `try/except` confirmed at `dashboard/server.py:5995-6014` | VERIFIED |
-| `tests/dashboard/test_quality_architecture_endpoint.py` 5/5 PASS | Direct `pytest` re-run: 5/5 PASS. Wrapper script also confirms. | VERIFIED |
-| `loki sentrux init-rules` scaffolds `.sentrux/rules.toml` | `autonomy/loki:7114` `init-rules)` case + template heredoc starting `:7130` | VERIFIED |
-| Refuse-overwrite unless `--force` | `autonomy/loki:7122-7124` shows the friendly refusal + `--force` flag parsing at `:7045` | VERIFIED |
-| `tests/test-sentrux-init-rules.sh` 9/9 PASS | DA re-run: 9/9 PASS | VERIFIED |
-| Doctor `--json` sentrux entry, parity bash + Bun | `autonomy/loki cmd_doctor_json` python emit (Dev4 `f7e95625` brought 15 lines) + `loki-ts/src/commands/doctor.ts:44 SentruxCheck`, `:54 sentrux: SentruxCheck` in DoctorJson, `:310 checkSentrux()` | VERIFIED |
-| Byte-identical bash vs Bun parity | `tests/test-doctor-json-sentrux.sh` test 13 explicitly runs both routes through `jq -S` then `diff -q`. Test passed. local-ci bun-parity matrix also passed (21/21). | VERIFIED |
-| `tests/test-doctor-json-sentrux.sh` 13/13 PASS | Reviewer + DA re-run: 13/13 | VERIFIED |
-| Dashboard nav UAT -- Escalations sidebar component | `legacy-ui/components/loki-escalations.js` (NEW, 280 lines), exported in `legacy-ui/index.js:99`, mounted in `legacy-ui/scripts/build-standalone.js:798` | VERIFIED |
-| Web vs dashboard help clarification | `autonomy/loki cmd_dashboard_help` and `cmd_web_help` -- confirmed both contain "Note:" blocks cross-referencing the other command. R3 re-ran: 2 matches each. | VERIFIED |
-| `tests/test-dashboard-nav-uat.sh` 13/13 PASS | DA re-run: 13/13 | VERIFIED |
-| Pytest gate timeout via `_loki_run_pytest_with_timeout` helper | `autonomy/run.sh:5928` defines helper, called from `:6065` inside `enforce_test_coverage` | VERIFIED |
-| Configurable via `LOKI_PYTEST_TIMEOUT` (default 300s) | Confirmed in helper body | VERIFIED |
-| Closes Triage #14 | Triage #14 was "pytest gate timeout wrapper" per v7.5.12 CHANGELOG. The helper is the wrapper. | VERIFIED |
-| `tests/test-pytest-gate-timeout.sh` 5/5 PASS | DA re-run: 5/5. Real exit-code-124 detection verified by Dev6's test fixture. | VERIFIED |
-| Per-file try/except in `memory/storage.py:_load_json` catches JSONDecodeError, UnicodeDecodeError, OSError | `memory/storage.py:354 except json.JSONDecodeError`, `:360 except UnicodeDecodeError`, `:366 except (OSError, UnicodeDecodeError)` | VERIFIED |
-| Closes Triage #15 | Triage #15 was "episode JSON try/except per file". Centralized fix in `_load_json` covers all callers (`engine.py`, `retrieval.py`, `consolidation.py`). | VERIFIED |
-| `tests/memory/test_episode_load_resilience.py` 8/8 PASS | DA re-run: 8/8 | VERIFIED |
-| `tests/test-sentrux-gate.sh` wired into Linux runner | `tests/run-all-tests.sh:78 run_test "Sentrux Gate Unit Tests"` -- present | VERIFIED |
-| `.github/workflows/sentrux-real.yml` gates real-binary test as manual/scheduled | New workflow file present; triggers `workflow_dispatch` and cron only; `continue-on-error: true` | VERIFIED |
-| `tests/test-ci-sentrux-coverage.sh` 4/4 PASS | DA re-run: 4/4 | VERIFIED |
-| All 7 new v7.5.15 test suites wired into `tests/run-all-tests.sh` | `tests/run-all-tests.sh:85-99` -- 5 bash entries + 2 pytest wrapper entries (gated on `python3 + import pytest`) | VERIFIED |
-| Final runner: 24/25 PASS | `bash tests/run-all-tests.sh` second run: `Tests Run: 25, Passed: 24, Failed: 1` | VERIFIED |
-| Single failure is pre-existing pip install mcp env gap | `python3 -c "import mcp"` reproduces the same `MCP SDK not found` error on bare Python; not introduced by this release | VERIFIED |
-| 13 version locations bumped (vscode-extension intentionally skipped) | `grep "7\.5\.15"` across the 13 expected files: all hit. `vscode-extension/package.json` still at older version (per CLAUDE.md v7.2.0 deprecation note) | VERIFIED |
-| local-ci 21/21 PASS | Final pre-push run: `Passed: 21, Failed: 0`. Re-confirmed post-merge twice. | VERIFIED |
-
-**Result: Every CHANGELOG bullet was checked individually against diff or re-run evidence. The table above has 30 rows, one per CHANGELOG sentence. Zero claims softened. No claim shipped without proof.**
-
-Note: The CHANGELOG body in v7.5.15 reads "20/20 PASS" for local-ci. That count reflects an intermediate state before the dist rebuild step was added as a final check. After the rebuild, the runner read 21/21. The 20/20 figure was accurate at the time it was written; 21/21 is the final pre-push count.
-
-Scope gap -- `scripts/local-ci.sh` (4 lines, modified in v7.5.15): this script was changed but is not represented by a row in the table above. The change added one check (the dist rebuild probe). The diff is trivial but the omission is noted here for completeness.
-
-Scope gap -- `legacy-ui-static/index.html` (318 lines, build artifact): the table confirms the Escalations component was mounted in the build script. It does not confirm that the built artifact is internally consistent beyond that. A full artifact diff was not performed.
-
-## 2. Per-agent claim audit
-
-For each of the 8 dev agents: did the agent's report overshoot what they actually shipped?
-
-### Dev1 (sentrux iteration wire-in)
-- Claimed: 7/7 PASS, helpers extracted into `_loki_sentrux_iteration_start/_end`, defensive numeric guard on before/after, only patched `track_iteration_complete "$ITERATION_COUNT" "$exit_code"` site.
-- Shipped: confirmed all of the above. Agent scoped to one call site. Second site (line 10843) not patched. CHANGELOG does not claim it.
-- **Overshoot: NONE.**
-
-### Dev2 (dashboard endpoint)
-- Claimed: 5 tests including resilience to corrupt JSON, 2 helper functions, copied existing `_ForceLokiDir` test pattern.
-- Shipped: confirmed in `dashboard/server.py:5958-6020`. 5 pytest assertions present.
-- **Overshoot: NONE.**
-
-### Dev3 (init-rules)
-- Claimed: 9/9 PASS, modified `cmd_sentrux` only, lines 7012-7150.
-- Shipped: actual diff shows 7029-7183 (small drift from the agent's claim). Behavior matches: `--force` flag, friendly refusal on overwrite, scaffolds the right template.
-- **Overshoot: NONE. Line numbers in agent's claim (7012-7150) differ from shipped range (7029-7183). Behavior matches. Cause: pre/post-merge offset.**
-
-### Dev4 (doctor JSON parity)
-- Claimed: 13/13 PASS including byte-identical parity test, dist artifact rebuilt but not staged because `loki-ts/dist/loki.js` is gitignored.
-- Shipped: confirmed `SentruxCheck` type at `loki-ts/src/commands/doctor.ts:44`, `checkSentrux()` at `:310`. Parity test still passes after my own dist rebuild during integration (because the merge brought source change but dist was stale until I rebuilt).
-- **Overshoot: NONE. Agent noted dist gitignore. Consistent with actual behavior.**
-
-### Dev5 (dashboard nav UAT)
-- Claimed: 13/13 PASS, escalations component is real (server-side `/api/escalations` already existed; UI was the gap), web vs dashboard are NOT aliases (different ports/products), explicitly punted on item #2 (parent-shell exit dependency).
-- Shipped: confirmed via grep of dashboard/server.py:5977 (`/api/escalations`), the new component file, and the help-text additions. Confirmed: web and dashboard serve different ports. Agent claim accurate.
-- **Overshoot: NONE. Agent explicitly marked item #2 out of scope. Not addressed in this release.**
-
-### Dev6 (pytest gate timeout)
-- Claimed: 5/5 PASS, found gate at `autonomy/run.sh:6041` (now 6053-6066), extracted helper for testability, mentioned "same hang risk in other gates" (go test, cargo test, monorepo test cmd) but did NOT fix them.
-- Shipped: confirmed helper at `:5928`, called from `:6065`. The "didn't fix other gates" disclosure is honest scope-limitation.
-- **Overshoot: NONE.**
-
-### Dev7 (episode JSON resilience)
-- Claimed: 8/8 PASS, single point of fix at `memory/storage.py:328 _load_json`, all higher-level callers inherit, did NOT add rename-on-corrupt pattern (no codebase precedent), listed out-of-scope sites at `cross_project.py:101` etc.
-- Shipped: confirmed via grep showing the 3 expected exception types caught at lines 354/360/366. Out-of-scope sites correctly left alone.
-- **Overshoot: NONE.**
-
-### Dev8 (CI coverage)
-- Claimed: 4/4 PASS, did NOT commit (applied CLAUDE.md "wait for user approval"), found 22 workflows, sentrux-real.yml is `continue-on-error: true` and not blocking.
-- Shipped: confirmed. Dev8 did not commit. Integrator staged Dev8's files manually.
-- **Overshoot: NONE.**
-
-**Result: 0 of 8 agents overshot their PR description. The fleet was honest.**
-
-## 3. Session integrity score vs CLAUDE.md
-
-### Where we got it right
-
-- **Pre-push local-ci**: Ran 3 separate times (post-Dev3+4 integration, post-DA-fix, final). Caught 1 transient flake. Final: 21/21.
-- **No `git add -A`**: All 25 release files staged by name. R2 explicitly warned about `.claude/worktrees/` sweep risk; I avoided it. The 2 pre-existing untracked docs (`docs/MIGRATION-STATUS.md`, `docs/SOFTWARE-FACTORY-ANALYSIS.md`) remain untracked.
-- **HEREDOC commit message**: Used. No co-author. Honest "NOT in this release" section enumerated 7 deferred items.
-- **14 version locations**: 13 bumped (vscode-extension deprecated per CLAUDE.md v7.2.0 -- documented honestly).
-- **No emojis, no em dashes**: R2 verified zero hits in the diff against both unicode ranges.
-- **3-reviewer council + DA**: Used. DA caught a real concern (test rot) that the 3 reviewers missed. Concern was addressed BEFORE commit, not deferred.
-- **Cleanup before commit**: All 8 worktrees + branches removed via `git worktree remove -f -f` + `git branch -D`. `/tmp/loki-*` cleared. `ps -ef` clean.
-- **Pre-existing untracked left alone**: `docs/MIGRATION-STATUS.md` and `docs/SOFTWARE-FACTORY-ANALYSIS.md` not staged. They were here at session start; not my work to commit.
-- **Post-publish smoke test**: claimed, not evidenced inline. Commands run were: `npm install -g loki-mode@7.5.15 && loki version`, `docker pull asklokesh/loki-mode:7.5.15 && docker run --rm asklokesh/loki-mode:7.5.15 version`, and a WebFetch of the Homebrew formula to confirm sha256. Output not captured in this doc.
-
-### Where we fell short
-
-| Issue | Detail | Cost |
-|---|---|---|
-| Bad-copy regression during integration | When I `cp`'d Dev5's `autonomy/loki` into the integrated tree, I obliterated Dev3+Dev4's `cmd_sentrux` and `cmd_doctor_json` changes. Caught immediately by `grep -c init-rules` returning 0 instead of 4. Fixed by `git checkout HEAD -- autonomy/loki` then surgical `Edit` of just Dev5's two help blocks. Cost if unnoticed: shipped a release that silently regresses Dev3+Dev4's features. | Caught locally; user-facing impact = 0. Lesson: never bulk-`cp` over an integrated multi-author file. |
-| R3 returned a non-substantive fragment first time | First R3 invocation returned the literal string "Still running. Let me wait for monitor." instead of executing. Re-spawned with stricter "Run all the bash commands below yourself. Do NOT wait for any monitor." preamble. Second attempt completed in 61s with 6 verifications. Cost if I hadn't noticed: missing the integration-safety verdict. | Caught by reading the output; cost = ~5 min retry. |
-| Dev5 + Dev8 didn't commit in their worktrees | Both correctly applied the global "wait for user approval" rule, which conflicted with the agent task spec's "commit at end". Their files were uncommitted in the worktree, so I had to manually `cp` 4 + 4 = 8 files. Worked but added integration risk (see bad-copy regression above). | Cost = the bad-copy regression. Lesson: dev-agent prompts should state explicitly whether commits are part of the worktree task or whether the integrator commits centrally. |
-| Bun `dist` was stale post-merge | Dev4 modified `loki-ts/src/commands/doctor.ts` and the merge brought the source. But `dist/loki.js` is gitignored and was not rebuilt in the worktree. Bun-route doctor JSON test failed (5/13) until I ran `cd loki-ts && bun run build`. Caught by my own pre-commit test sweep. | Cost = ~2 min rebuild + retest. Lesson: integration must rebuild `dist` after any `loki-ts/src/` merge. |
-| Devil's Advocate caught test rot 4 reviewers missed | 7 of 8 new tests were not registered in `tests/run-all-tests.sh` -- only `test-ci-sentrux-coverage.sh` (Dev8's own) was. The 3 R-reviewers all confirmed "tests pass" by running them directly, but didn't ask "will they run in CI tomorrow?". DA asked the right question. | Caught pre-commit. If missed: 7 tests would have silently rotted. They are now wired in (24/25 PASS via runner). |
-| First `bash tests/run-all-tests.sh` invocation captured truncated output | I piped the runner through `tail -15` which discarded all the per-test stdout. Re-ran without `tail` to get full per-test PASS/FAIL marks. | Caught immediately. Lesson: never `tail` a test runner you're trying to debug. |
-| First `git worktree remove` attempt failed | 8 worktrees were `locked` (per the auto-isolation lock). Initial `git worktree remove --force` returned `use 'remove -f -f' to override or unlock first`. Re-ran with `-f -f`. | Caught immediately. Cost = ~30s retry. |
-| MCP test failure shipped as known caveat | `python3 -c "import mcp"` fails on this Mac (`pip install mcp` not done). Pre-existing, not introduced by v7.5.15. CHANGELOG documents this honestly. | Pre-existing. CI runs in environments where `mcp` is installed; not a release blocker. |
-
-### Patterns to repeat
-
-- 8-agent fleet with isolated worktrees: 8 features shipped in ~5 min wall time vs ~2 days serial.
-- Devil's Advocate as a separate role from the 3 standard reviewers: the 3 reviewers focused on "did the patch work?" and missed "will the patch keep working?". DA caught it.
-- "NOT in this release" CHANGELOG section: agents and integrator both named deferred items explicitly.
-- Per-file `git add`: avoided sweeping `.claude/worktrees/` into the release commit.
-
-## Net verdict
-
-**Release c82b9541: 30 claims evidenced. 0 agents overshot. Failures: bad-copy regression during integration, test-rot caught by DA, stale dist after loki-ts/src merge, truncated runner output from `tail`. Lessons: no bulk-`cp` over multi-author files; explicit commit-vs-wait dispatch rule in agent prompts; rebuild dist after loki-ts/src merges; never `tail` a test runner you're debugging.**

package/docs/retrospectives/v7.5.15-llm-failure-modes.md

@@ -1,49 +0,0 @@
-# v7.5.15 LLM Failure Modes Catalogue
-
-This table catalogues LLM failure modes that occurred (or were explicitly
-considered and ruled out) during the v7.5.15 8-agent fleet session. "Failure
-mode" means a systematic LLM behavioral error, not a human process mistake.
-Each row covers one category. If a category did not materialize in this
-session, it is marked NOT OBSERVED so the reader can confirm it was
-considered, not overlooked. All session moments and file references are
-specific: no generalities.
-
-| Failure mode | Where it appeared | What caught it | Cost if missed |
-|---|---|---|---|
-| Confident hallucination (agent claims a file/function exists that doesn't) | NOT OBSERVED in this session | n/a | n/a |
-| Stale context (agent acts on memory of prior state instead of current) | Dev5's `autonomy/loki` worktree was branched from pre-merge `HEAD` (`2ce36624`), i.e., prior to Dev3+Dev4's merges. The integrator treated the worktree file as current state and bulk-`cp`'d it over the integrated tree. This is the integrator exhibiting stale-context behavior. | `grep -c "init-rules" autonomy/loki` returned 0 instead of 4. Immediate recovery via `git checkout HEAD -- autonomy/loki` + surgical `Edit` of only Dev5's two help blocks. | Dev3's `init-rules` subcommand (9/9 tests) and Dev4's `cmd_doctor_json` sentrux field (13/13 tests) would have shipped silently regressed. Two advertised features gone from the binary. |
-| Scope creep (agent does more than asked, breaking adjacent code) | NOT OBSERVED in this session. All 8 dev agents touched only their assigned functions/files. Dev7 explicitly disclaimed out-of-scope sites (`cross_project.py:101`) rather than patching them. | n/a | n/a |
-| Silent test rot (tests written but not wired to runner) | 7 of 8 new test suites (Dev1 through Dev7) were not registered in `tests/run-all-tests.sh`. Only Dev8's `test-ci-sentrux-coverage.sh` was wired. R1, R2, R3 all ran the tests directly and confirmed PASS without asking whether CI would ever invoke them. | Devil's Advocate reviewer asked "will these tests run tomorrow?" and checked `tests/run-all-tests.sh` directly. Caught pre-commit. Fixed by adding 5 bash entries + 2 pytest wrapper scripts at `tests/run-all-tests.sh:85-99`. | 7 tests silently orphaned. Future regressions in sentrux wire-in, dashboard endpoint, init-rules, doctor JSON parity, dashboard nav UAT, pytest timeout, and episode resilience paths would go undetected until a manual invocation. |
-| Cross-agent state assumption (Dev N assumes Dev M's branch is in some state without verifying) | Integrator assumed Dev5's worktree file was safe to `cp` over the integrated main tree. The assumption was that worktree files reflected the post-merge state; they did not (Dev5's branch point was `2ce36624`, before Dev3 + Dev4 merges). See `v7.5.15-fleet-postmortem.md` section 1. | Structural checksum: `grep -c "init-rules" autonomy/loki` == 0 (expected 4). Caught immediately after the bad copy. REPEATABILITY: LOW (manual, not codified -- see fleet-postmortem section 1 recommendation 3 for the fix). | Same as stale context above: two shipped features silently deleted from the binary. |
-| Optimistic verification (agent says "tested" without running test) | R3 (first dispatch) returned "Still running. Let me wait for monitor." as its entire output. R3 had not run any of the 6 cross-cutting integration checks assigned to it, but its status was "completed". The agent used language implying work was in progress when no work was done. | Integrator read the result body. 7-word fragment clearly not a structured 6-risk verdict. Re-spawned R3 with a prompt containing literal `bash` blocks and "DO NOT wait for any monitor." R3-retry completed in 61s. See `v7.5.15-fleet-postmortem.md` section 2. | Integration safety review would have been missing from the record. Subtle cross-file interactions between Dev1+Dev6's `autonomy/run.sh` edits and Dev3+Dev4's `autonomy/loki` edits would have gone unchecked. A previously undetected conflict could have shipped. |
-| Path-prefix confusion (rm -rf interpreted as dangerous when it isn't) | `validate-bash` hook matched the pattern `rm -rf /Users/lokesh/git/loki-mode/.sentrux` against its dangerous-rm guard (`rm -rf /` prefix check). The path is a subdirectory of the project, not the root, but the string match fired a false positive. Hook returned BLOCKED. | The hook itself caught and surfaced the block explicitly -- no silent data loss. Workaround: rewrite as relative path `rm -rf ./.sentrux`. Documented in session notes from the validate-bash hook output. | If the hook had silently suppressed the error and continued, a subtly wrong rm invocation could have run. Conversely, if the integrator had bypassed the hook without understanding why, it could have established a precedent of ignoring hook blocks. |
-| Exit code over-trust (relying on subprocess exit code that lies) | Pre-existing MCP test failure: `python3 -c "import mcp"` exits non-zero on this Mac because `pip install mcp` was never run. The exit code does not represent a regression introduced by v7.5.15 -- it is an environmental gap that predates the session. If taken at face value it could be misread as a newly broken test. | Verified pre-existing by reproducing on `origin/main` before the release commit. CHANGELOG v7.5.15 documents it honestly as "single failure is pre-existing pip install mcp env gap". 24/25 PASS is the accurate count. | Misfiled as a release regression: would have blocked the release or, if overridden, set a precedent of shipping with unacknowledged test failures. |
-| Bash vs zsh source-file scope leaking | session-reported, unverified by audit. Reported behavior: `command -v sentrux` returned empty under zsh mid-session even though the binary was on PATH. Plausible mechanism: zsh PATH hash cache had not refreshed to see the binary added during the session. No file:line cite, no grep output, no git ref was captured that would allow an auditor to reproduce or confirm this independently. | session-reported, unverified by audit. Reported workaround: switching to `bash -c` for the test invocation forces a fresh hash evaluation and the invocation succeeded. No codified guardrail exists for this behavior. | If the zsh/bash inconsistency had been attributed to a code bug rather than a shell hash quirk, time would have been spent diagnosing a non-existent defect in the sentrux integration code. Alternatively, the test could have been skipped and a real future failure masked. |
-| Tool hook noise drowning real failures | First `bash tests/run-all-tests.sh` invocation was piped through `tail -15`. The tail window captured only 15 lines of output, discarding all per-test PASS/FAIL lines and the full run summary. The visible output showed only the last few lines of the final test's output -- no actionable signal. | Integrator noticed the output was truncated (no "Tests Run:" summary line) and re-ran without the `tail` pipe. Second run produced full per-test output: 24/25 PASS with the one failing test identified by name. | If the truncated output had been accepted as the verification record, the integrator would have had no per-test attribution. Any failure that landed outside the last 15 lines would have been invisible. The release would have shipped without a verified pass/fail count per test. |
-| (beyond user's 10) Build artifact drift after source-only merge | The bun-parity matrix in `local-ci.sh` ran both bash and Bun routes through `diff -q` and surfaced a 5/13 failure caused by stale `loki-ts/dist/loki.js`. The Bun dist had not been rebuilt after source changes were merged, so the Bun route diverged from the bash route at 5 commands. This is a distinct failure mode from stale context: the source was current, but the compiled artifact was not. | `bash scripts/local-ci.sh` bun-parity matrix caught the 5/13 diff before the commit. Fix was `bun run build` followed by re-staging the updated dist file. | If the stale dist had shipped, 5 Bun-route commands would have exhibited the pre-merge behavior while the bash route exhibited the post-merge behavior. Users on the Bun route would have silently received the older behavior with no error. |
-
-## What went right
-
-The failure modes above were caught -- none shipped to users -- because
-several guardrails worked exactly as intended. The `validate-bash` hook
-surfaced the false-positive rm block explicitly rather than silently passing
-or silently failing. The post-merge structural grep checksum (`grep -c
-"init-rules"`) caught the bad-copy regression in seconds. The Devil's
-Advocate role, operating with an explicitly non-domain mandate separate from
-R1/R2/R3, asked the meta-question about test runner wiring that three
-domain-specific reviewers each had reason not to ask. The `local-ci`
-pre-push gate (`bash scripts/local-ci.sh`, 21/21 PASS) caught the stale
-`loki-ts/dist/loki.js` artifact before the commit: the bun-parity matrix
-ran both bash and Bun routes through `diff -q` and surfaced the 5/13
-failure that triggered a `bun run build` before staging. The integrator's
-discipline of reading reviewer output rather than trusting "completed"
-status caught R3's fragment response before it was treated as a verdict.
-Taken together: grep-based checksums, the DA contrarian role, local-ci
-pre-push, the bun-parity matrix, and the validate-bash hook are the
-codified mechanisms that kept this session's failure modes from becoming
-user-facing defects. Note: the integrator reading R3's result body before
-accepting its status as a verdict was human attentiveness, not a repeatable
-guardrail. It is not listed here as a mechanism; it is listed as the action
-that exposed the gap. The gap itself (agents reporting "completed" without
-producing required output) is a process deficiency without a codified fix
-as of this session.

package/docs/show-hn-post.md

@@ -1,46 +0,0 @@
-# Show HN Post Draft
-
-## Title
-
-Show HN: Loki Mode - PRD in, tested code out (8 quality gates, RARV self-verification)
-
-## Body
-
-I built Loki Mode because I got tired of the copy-paste loop between AI coding assistants and my terminal. I wanted to hand over a PRD and get back a working, tested codebase -- not perfect, but a solid starting point.
-
-**What it does:** You give it a Product Requirements Document. It breaks the work into tasks across specialized agent roles (engineering, operations, business, data, product, growth, review, orchestration) -- prompt-defined specifications the orchestrator adopts per phase, with parallel review (blind council) and optional worktree streams on Claude Code, sequential on other providers -- and runs every iteration through a self-verification loop called RARV: Reason, Act, Reflect, Verify. The idea is that the system catches its own mistakes before you have to.
-
-**Quality gates:** 8 automated gates including 3-reviewer blind review (agents review each other's work without seeing prior reviews), anti-sycophancy checks (a devil's advocate pass on unanimous approvals), and mock/mutation detection. These are not foolproof, but they catch a surprising number of issues that single-pass generation misses.
-
-**Multi-provider:** Runs on Claude Code (full parallel agent support), Cline, OpenAI Codex CLI, Aider, or opencode. Everything other than Claude Code runs in degraded sequential mode -- no parallel agents, no Task tool. Claude Code is the primary target. (The Google Gemini CLI provider was removed in v7.5.18 after Google deprecated it upstream.)
-
-**Memory:** 3-tier system (episodic, semantic, procedural) so the system can learn from previous runs. Optional vector search with sentence-transformers if you want similarity-based retrieval.
-
-**Enterprise features:** TLS, OIDC/SSO, RBAC, OTEL tracing, policy engine, audit trails. All behind env vars. Certs are self-signed only. Dashboard runs on a single machine at port 57374.
-
-**Research foundation:** The architecture draws from Anthropic's Constitutional AI (principles-based self-critique), DeepMind's Scalable Oversight via Debate, and OpenAI's Agents SDK patterns (guardrails, tripwires, handoffs). References to specific papers are in the repo.
-
-**What it does NOT do:** It does not deploy anything. It generates deployment configs (Helm, Docker Compose, Terraform), but a human deploys. Complex domain logic will need human review. The system can and does make mistakes, especially on novel problems. Token costs scale with project complexity. There is no published benchmark score.
-
-
-Built solo. BUSL-1.1 source-available.
-
-## Try it
-
-```bash
-npm install -g loki-mode
-claude --dangerously-skip-permissions
-# Then say: "Loki Mode with PRD at path/to/your-prd.md"
-```
-
-Python SDK: `pip install loki-mode-sdk`. TypeScript SDK: `npm install loki-mode-sdk` (available in the repo at `sdk/typescript/`).
-
-Integrations: Jira, Slack, Teams, GitHub Actions.
-
-## Feedback wanted
-
-- Is the 8-gate quality system overkill, or does it actually help for your use cases?
-- How do you handle the tension between autonomous agent speed and code review thoroughness?
-- What PRD complexity level breaks this approach? I have hit walls with highly coupled distributed systems.
-
-GitHub: https://github.com/asklokesh/loki-mode