loki-mode 11.2.2 → 11.3.1

package/docs/P2-SPEC-ROBUSTNESS-PLAN.md

@@ -1,192 +0,0 @@
-# P2 Spec Robustness Plan (P2-1 spec interrogation gate + P2-2 assumption ledger)
-
-Status: design for implementation. No version bump, no commit in this arc.
-
-## Goal
-
-Loki must stay accurate even when the input spec is WRONG, ambiguous, or
-incomplete. Today two building blocks already detect spec defects but neither
-feeds the autonomous loop:
-
-- `autonomy/grill.sh` invokes the provider once with a Devil's-Advocate prompt
-  and writes 10-15 hardest spec questions to `.loki/grill/report.md`. It is
-  CLI-only (`grep grill autonomy/run.sh` = 0 invocations) and nothing reads its
-  output.
-- `autonomy/prd-analyzer.py` detects missing PRD dimensions and has a
-  deterministic `_make_assumption()` map, writing `.loki/prd-observations.md`,
-  which nothing reads. Its interactive Q&A is inert in non-TTY (autonomous) runs.
-
-The fix: run interrogation automatically in DISCOVERY, classify the findings,
-record every spec gap as a first-class ASSUMPTION in a tracked ledger, BLOCK
-completion while high-severity assumptions are unconfirmed-and-unacknowledged,
-and surface the ledger in the proof-of-done output. Defects are SURFACED as
-recorded assumptions, never silently autocorrected.
-
-## Core design decision: auto-acknowledgment lifecycle (prevents the trap)
-
-A naive "block completion while any high-severity assumption is unconfirmed"
-hard-blocks EVERY ambiguous run to max-iterations, because in autonomous
-(non-TTY) mode no human can ever set `confirmed=yes`. We never reach the
-"done, plus here is what I assumed" output the goal demands.
-
-Resolution: split the gate from the lifecycle.
-
-- The gate `council_assumption_ledger_gate` is a PURE function of ledger state.
-  It blocks iff an entry has `severity=high AND confirmed=false AND
-  acknowledged=false`.
-- The auto-acknowledgment lifecycle lives in run.sh (NOT in the gate). Once an
-  assumption has been written into the ledger AND injected into the build prompt
-  at least once, run.sh marks it `acknowledged=true`. Default-on; opt-out
-  `LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1` keeps a human-in-the-loop path where only
-  `confirmed=true` clears the block.
-
-This is the OPPOSITE of silent autocorrect: the assumption is recorded,
-injected into the agent's prompt, and surfaced in proof-of-done. Acknowledgment
-records "Loki has SEEN this gap and proceeded with a stated default", not "Loki
-hid it". The gate still has teeth on the first iteration (high-sev unacknowledged
-blocks) and in the require-confirm path.
-
-## Severity rule (deterministic, no LLM)
-
-grill emits no severity. Classify by section / keyword on the read side:
-
-- HIGH: security blind spots; scale/reliability blind spots; missing or
-  untestable acceptance criteria; any line containing contradiction keywords
-  (contradict, conflict, inconsistent, mutually exclusive).
-- MEDIUM: ambiguities; unstated assumptions; underspecified behavior; all
-  prd-analyzer missing-dimension assumptions.
-
-This guarantees a HIGH tier exists (so the gate has teeth) and is fully
-deterministic (so tests are reproducible).
-
-## Taxonomy mapping (classification, read-side only)
-
-grill section -> finding class:
-- "Ambiguities and missing acceptance criteria" -> ambiguous (HIGH if the line
-  references acceptance criteria / testable / measurable; else MEDIUM)
-- "Unstated assumptions" -> underspecified (MEDIUM)
-- "Security blind spots" -> missing (HIGH)
-- "Scale and reliability blind spots" -> missing (HIGH)
-- any line with a contradiction keyword (any section) -> contradictory (HIGH)
-- prd-analyzer missing dimensions -> missing (MEDIUM, deterministic default)
-
-"None identified." lines are skipped (no fabricated findings).
-
-grill output contract is NOT changed (it is parsed by the loki-grill skill).
-We classify a COPY of its markdown; grill.sh stays byte-identical.
-
-## No-fabrication rule for ledger content
-
-A grill finding is a QUESTION, not a resolution. The ledger `assumption` field
-for a grill-derived gap is an honest "spec gives no answer; proceeding with the
-implementer default for <area>" plus `affects=<area>`. We do NOT invent a
-specific resolution the build will not actually follow. prd-analyzer assumptions
-reuse its existing deterministic `_make_assumption()` text verbatim.
-
-## Ledger schema (`.loki/assumptions/`)
-
-One JSON file per assumption: `.loki/assumptions/<id>.json`, plus a
-human-readable `.loki/assumptions/ledger.md` rollup regenerated on each write.
-Each entry:
-
-```json
-{
-  "id": "a-0001",
-  "gap": "<the spec defect / unanswered question, verbatim>",
-  "assumption": "<honest stated default Loki proceeds with>",
-  "why": "<why this assumption / where the gap came from: grill|prd-analyzer>",
-  "severity": "high|medium",
-  "class": "ambiguous|contradictory|underspecified|missing",
-  "affects": "<area, e.g. security, acceptance-criteria, data-model>",
-  "source": "grill|prd-analyzer",
-  "confirmed": false,
-  "acknowledged": false,
-  "created_at": "<iso8601>"
-}
-```
-
-Stable id = `a-` + zero-padded counter over existing files (idempotent: a second
-DISCOVERY run with the same findings does not duplicate; dedupe on the `gap`
-text hash).
-
-## Build surface (files + functions)
-
-1. NEW `autonomy/spec-interrogation.sh` (sourced by run.sh; standalone-testable):
-   - `spec_interrogation_classify_report <report.md path>`: pure classifier.
-     Reads grill markdown, emits one TSV/JSON finding per question line with
-     class + severity. Takes a file so a fixture report drives the test with no
-     `claude` call.
-   - `spec_interrogation_severity_for <section> <line>`: deterministic severity.
-   - `spec_ledger_write <gap> <assumption> <why> <severity> <class> <affects>
-     <source>`: idempotent writer (dedupe on gap hash) -> `.loki/assumptions/`.
-   - `spec_ledger_rebuild_md`: regenerate `.loki/assumptions/ledger.md`.
-   - `spec_ledger_high_unresolved_count`: count entries with
-     `severity=high AND confirmed=false AND acknowledged=false` (gate input;
-     also reused by the summary).
-   - `spec_ledger_acknowledge_all`: set `acknowledged=true` on all entries
-     (auto-ack lifecycle helper; default path).
-   - `spec_interrogation_run <spec_path>`: orchestrator. Default-on
-     (`LOKI_SPEC_GRILL=0` opts out). Provider-aware: source grill.sh, call
-     `grill_check_provider`; if provider absent, log honest message, skip the
-     grill subcall (NO fabricated questions), but STILL fold prd-analyzer
-     missing-dimension assumptions into the ledger so degrade surfaces something
-     non-blocking. On provider present: run `grill_main` (writes report.md),
-     classify it, write ledger entries. Always non-fatal to the run.
-
-2. `autonomy/run.sh` DISCOVERY (~13056, after prd-analyzer + council_init,
-   before the iteration loop): source spec-interrogation.sh and call
-   `spec_interrogation_run "$prd_path"`. This is the grep-able grill invocation
-   the task requires. Best-effort (`|| true`), never blocks startup.
-
-3. `autonomy/run.sh` auto-ack lifecycle: after the build prompt is constructed
-   each iteration (assumptions are injected into the prompt via build_prompt),
-   call `spec_ledger_acknowledge_all` UNLESS
-   `LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1`. Inject the high-severity assumption
-   list into the build prompt (so the agent sees the gaps it must respect).
-
-4. `autonomy/completion-council.sh` `council_assumption_ledger_gate` (new),
-   slotted into `council_evaluate` right after `council_evidence_gate`
-   (mirrors 2510-2513). Same defensive `COUNCIL_STATE_DIR` default, opt-out
-   `LOKI_ASSUMPTION_GATE=0`. Blocks iff `spec_ledger_high_unresolved_count > 0`.
-   Writes `.loki/council/assumption-block.json` on block, removes it on pass.
-   Also wired into the completion-promise route in run.sh (~14525 pattern) and
-   the code_review gate chain (~15013) so the promise path cannot bypass it.
-
-5. `autonomy/run.sh` `build_completion_summary` (~2637): emit an
-   "Assumptions recorded: N (M high-severity)" block into COMPLETION.txt and the
-   ledger list, plus the count into completion.json. So "done" means "done, plus
-   here are the N places your spec was ambiguous and what I assumed."
-
-6. NEW `tests/test-spec-interrogation.sh` (bash convention, ok/bad counters,
-   source the module, mktemp fixtures):
-   - (a) classifier on a fixture grill report writes classified findings to the
-     ledger (ambiguous/contradictory/underspecified/missing + high/medium).
-   - (b) a ledger with one high/confirmed:false/acknowledged:false entry makes
-     `council_assumption_ledger_gate` return 1 (BLOCK) and write
-     assumption-block.json.
-   - (c) clean spec (no high-sev entries, or all acknowledged) -> gate returns 0
-     (no spurious block), no block file.
-   - (d) no provider -> `spec_interrogation_run` degrades cleanly: honest
-     message, prd-analyzer assumptions still folded (medium, non-blocking), run
-     proceeds, gate passes.
-
-## Gate reachability (resolved open question)
-
-The existing gates fire from THREE sites: `council_evaluate` (~2510), the
-completion-promise route (~14525), and the code_review gate chain (~15013). The
-new gate is wired into all three so high-sev unacknowledged assumptions cannot
-slip through the promise path.
-
-## Opt-out knobs (all default-on, intelligent)
-
-- `LOKI_SPEC_GRILL=0` -> skip interrogation entirely.
-- `LOKI_ASSUMPTION_GATE=0` -> gate is pass-through.
-- `LOKI_ASSUMPTIONS_REQUIRE_CONFIRM=1` -> require human `confirmed=true`
-  (disables auto-ack); the human-in-the-loop path.
-
-No "user must decide the type" knob. Classification + severity are automatic.
-
-## Constraints
-
-No emojis, no em dashes, no version bump, no commit, no push. Provider-aware,
-degrade cleanly, no fabricated questions when provider absent.

package/docs/PLANS-INDEX.md

@@ -1,32 +0,0 @@
-# Plans Index
-
-This index maps each historical plan doc to its status. Plan docs are kept as design history; a 'shipped' plan's feature is live in the code.
-
-| Plan | Status | Notes |
-|---|---|---|
-| BUILD-HUD-PLAN.md | shipped | Live in-terminal build HUD; `LOKI_HUD` / `[HUD]` in `autonomy/run.sh`, CHANGELOG "Live in-terminal build HUD". |
-| history/v8-config-plan.md | shipped | Unified config file; `--config` / `--vars` / `--env-file` flags in `autonomy/loki`. |
-| CRASH-REPORTING-PLAN.md | shipped | Crash-reporting + auto-fix; `cmd_crash()` in `autonomy/loki` (`loki crash`). |
-| DEPLOY-PLAN.md | shipped | `loki deploy` advisory print-only; CHANGELOG "`loki deploy`: advisory, print-only deploy guidance". |
-| FAILURE-MEMORY-PLAN.md | shipped | Failure-memory loop; `FailureMode` schema in `memory/schemas.py`. |
-| FEAT-PRDREUSE-DOCKER-PLAN.md | shipped | PRD-reuse + Docker batch; Docker dashboard/port + PRD-reuse present in `autonomy/loki`. |
-| MERGE3-PLAN.md | shipped | Purple-Lab-into-Dashboard integration; `/lab/` mount in `dashboard/server.py`. |
-| P0-SWEEP-PLAN.md | shipped | Verification-credibility sweep; wired detectors are part of the 8-gate system. |
-| P2-SPEC-ROBUSTNESS-PLAN.md | shipped | Spec interrogation gate + assumption ledger; part of quality-gates spec robustness. |
-| PRD-REUSE-DONE-RECOGNITION-PLAN.md | shipped | PRD-reuse done-recognition gate; reuse-then-verify behavior in the engine. |
-| PREVIEW-LINK-PLAN.md | shipped | `loki preview --public`; `_preview_public` in `autonomy/loki`, CHANGELOG "`loki preview --public`". |
-| R10-MARKETPLACE-PLAN.md | shipped | Agent/template marketplace (install-from-source); `loki template` marketplace in `autonomy/loki`. |
-| R6-ROLLBACK-CHECKPOINT-PLAN.md | shipped | 1-click rollback + checkpoint UX; `cmd_rollback()` / `rollback)` dispatch in `autonomy/loki`. |
-| R7-ZERO-CONFIG-FIRST-RUN-PLAN.md | shipped | Zero-config first run; welcome/first-run path in `autonomy/loki`. |
-| R8-SHAREABLE-TEAM-ASSETS-PLAN.md | shipped | Exportable/importable team assets; `cmd_export()` / `cmd_import()` in `autonomy/loki`. |
-| R9-OPEN-CORE-HOOKS-PLAN.md | shipped | Open-core seams (BUSL-1.1); open-core seam references in `autonomy/loki`. Seams only; no hosted backend (by design). |
-| RARV-C-100X-PLAN.md | active | v8.0.0 native-primitives arc; v8 lives on the `feature/v8-agent-sdk` branch, not yet merged to main. |
-| RARV-C-LOOP-EFFICIENCY-PLAN.md | superseded | Self-marked SUPERSEDED by RARV-C-100X-PLAN.md (v8.0.0 arc); anchors drifted, kept as history. |
-| SHAREABLE-PROOF-PLAN.md | shipped | Opt-in shareable proof-of-run (v7.19.3) preserving zero-egress posture. |
-| SONNET5-DEFAULT-PLAN.md | shipped | Sonnet 5 default execution model; `v7.104.0: Sonnet 5 is the default` in `providers/claude.sh`. |
-| TASKLIST-ACCURACY-PLAN.md | shipped | Dashboard task-list accuracy fix; task-list handling in `dashboard/server.py`, CHANGELOG v7.104.x task-list fixes. |
-| UNCERTAINTY-ESCALATION-PLAN.md | shipped | Uncertainty-gated escalation (v7.19.2); uncertainty escalation logic in `autonomy/run.sh`. |
-| VERIFIED-COMPLETION-PLAN.md | shipped | Verified completion (v7.19.1); verified-completion gate in `autonomy/run.sh` + `autonomy/completion-council.sh`. |
-| WELCOME-OPENER-PLAN.md | shipped | Welcome opener ("magic opener"); `welcome` path in `autonomy/loki`. |
-| history/v8-agent-sdk-plan.md | shipped | The v8 Anthropic SDK runtime migration; shipped on `feature/v8-agent-sdk` as v8.0.0 + v8.1 (`loki-ts/src/runner/sdk_invoker.ts`, `sdk_mode.ts`, CHANGELOG v8.0.0/v8.1). Feature-branch-only, not yet merged to main. |
-| V8-SDK-RESEARCH-RAW.md | shipped | Research notes underpinning V8-AGENT-SDK-PLAN; design history for the v8 SDK arc. |