loki-mode 8.5.2 → 8.6.1

package/docs/brownfield.md

@@ -0,0 +1,120 @@
+# Working on a codebase you already have
+
+Most of this category is built for starting from nothing. If you already have a
+repository -- especially a large, private, awkward one -- your options narrow
+fast.
+
+## Where the tools actually stand
+
+Verified from vendor documentation, 2026-07-31:
+
+| Tool | Existing repository |
+|---|---|
+| Lovable | **Cannot import one.** "You can only export from Lovable to GitHub"; two-way sync begins only after Lovable creates the repo. |
+| Replit Agent | Imports GitHub (public and private), Figma, ZIP -- into Replit's environment. |
+| Cursor | Indexes your repo; embeddings are uploaded, obfuscated and encrypted. |
+| Devin | Indexes the repo, plus YAML blueprints producing snapshots each session boots from. |
+| Loki | Runs in place, where the code already is. |
+
+That last row is the whole difference, and it is not a preference. For a private
+monorepo with internal dependencies and submodules, "upload it to our
+environment" is often not a thing anyone is permitted to do.
+
+**Credit where it is due:** Devin has the strongest documented modernization
+story of the four -- named playbooks for COBOL, Java upgrades, and
+SAS-to-PySpark. If you want a vendor-run modernization program, look at them
+seriously. What follows is what we do differently, not a claim that they are
+bad at this.
+
+## Start here: a read-only assessment that costs nothing
+
+```sh
+loki heal ./your-repo --assess --json
+```
+
+No provider call, no API key, no spend, no writes. It reports:
+
+- a **maturity level** with the reason stated (for example: "No test/spec files
+  detected: changes are unguarded")
+- **ranked targets** with blast-radius reasoning per file ("isolated (no inbound
+  imports -> low blast radius), 12 LOC")
+- **debt signals**: test ratio, TODO density
+- **the runtime it declares**: Node engine constraint, dependency count, and the
+  frameworks actually present in the manifest
+- **dependency lock status**
+
+This is the honest opening move: you learn where to start before committing to
+anything.
+
+### What it deliberately does not tell you
+
+`dependency_staleness` reports `unknown`, always, offline. We know your manifest
+pins lodash 3.x; we do not know what is current upstream without a network call,
+and we will not guess. That refusal is the same reason the assessment works
+inside an air-gapped network at all.
+
+## The healing phases
+
+```sh
+loki heal ./your-repo --phase archaeology   # map dependencies, catalog friction
+loki heal ./your-repo --phase stabilize     # add observability and tests, no behavior change
+loki heal ./your-repo --phase isolate       # adapter boundaries between components
+loki heal ./your-repo --phase modernize     # replace one component at a time, behind adapters
+loki heal ./your-repo --phase validate      # prove behavioral equivalence against the baseline
+```
+
+These call a provider and cost money. `--assess` does not.
+
+## Behavioral equivalence is the part worth arguing about
+
+Every tool in this category will tell you it preserved your business logic.
+Devin's COBOL page says it preserves "critical functionality." What none of them
+document is a *procedure* for proving it.
+
+That is the axis we build on:
+
+- **characterization tests** capture what the system does today, quirks
+  included, before anything is modernized
+- **friction classification** distinguishes accidental mess from load-bearing
+  weirdness -- the 30-second sleep that looks stupid and is actually a race-
+  condition fix nobody documented
+- **a backward-compatibility auditor** blocks removal of unclassified friction
+- **the validate phase** checks behavior against the recorded baseline
+
+Then the [Evidence Receipt](../README.md#the-evidence-receipt-dont-trust-the-agent-check-it)
+records what was proven and what was not, bound to the specific diff.
+
+"We prove behavior is unchanged" is a stronger claim than "we preserve business
+logic," and it is the one you can check.
+
+The full procedure -- what each phase does, what the friction taxonomy
+distinguishes, and where the safety gates sit -- is in
+[skills/healing.md](../skills/healing.md), with the research it draws on in
+[references/legacy-healing-patterns.md](../references/legacy-healing-patterns.md).
+
+### The friction question, concretely
+
+The hardest part of a legacy migration is not translating syntax. It is telling
+the difference between:
+
+- a `sleep 30` that is genuinely dead weight, and
+- a `sleep 30` that is the only thing preventing a race condition nobody wrote
+  down, whose author left in 2019
+
+Delete the second and the system breaks in production, weeks later, in a way
+nobody connects to the migration. This is why the auditor blocks removal of
+*unclassified* friction: not because the friction is sacred, but because
+"we do not know what this does yet" is a real state that deserves a name
+instead of a guess.
+
+## Honest scope
+
+- **Measured and working:** `--assess` on real repositories, verified by
+  execution.
+- **Implemented, not measured here:** the five mutating phases need a provider
+  and real spend; this page does not claim an end-to-end benchmark we have not
+  published.
+- **We do not do COBOL.** If your problem is a mainframe, we are not your
+  answer today.
+- **Your code stays put.** Nothing is uploaded to us -- there is no "us" in the
+  data path. See [cost controls](./cost-controls.md) for how spend is bounded.

package/docs/cost-controls.md

@@ -0,0 +1,88 @@
+# Cost controls
+
+You set the ceiling. We stop at it, and the receipt tells you where the money
+went.
+
+## Why this page exists
+
+"I paid for the AI's own mistakes" is one of the sharpest complaints in this
+category, and it is worth being precise about how our model differs.
+
+Most competitors sell credits. Lovable has already addressed the objection
+directly -- their "Try to fix" button does not consume credits, and their
+troubleshooting docs push you toward reverting or replanning instead of
+retrying the same prompt. That is a good policy and we are not claiming to have
+invented a better one.
+
+**Our model is different in kind: you bring your own provider credentials.** We
+never bill you, because we are never in the payment path. What we owe you
+instead is a hard ceiling and an honest account of what was spent -- which is
+what this page describes.
+
+## The three caps
+
+They bound different things, and a run that stalls needs all three.
+
+| Cap | Bounds | Default |
+|---|---|---|
+| `LOKI_BUDGET_LIMIT` | Total spend, in USD | unset (no cap) |
+| `LOKI_MAX_ITERATIONS` | Number of iterations | 1000 |
+| `LOKI_MAX_DURATION` | Wall-clock time | unset (no cap) |
+
+```sh
+LOKI_BUDGET_LIMIT=25 loki start ./prd.md
+loki start ./prd.md --max-duration 90m
+loki config set budget 25
+```
+
+**Why three and not one.** Spend and iterations both assume forward progress. A
+run that *stalls* -- a hung provider call, a wedged subprocess -- burns hours
+while spending almost nothing and completing no iteration, so neither of those
+breakers ever trips. The wall-clock cap is the one that catches it. We added it
+after a run burned $34 reaching an external timeout.
+
+## Hitting a cap is a FAILURE, not a success
+
+This is the part that matters for anyone automating against us.
+
+All three caps produce a **terminal failure**: exit 20 under
+`LOKI_DURABLE_STATE=1`, with a distinct status (`budget_exceeded`,
+`max_iterations_reached`, `max_duration_reached`) so the receipt and `loki why`
+can tell you *which* ceiling you hit and therefore which one to raise.
+
+`budget_exceeded` used to exit **0**, on the reasoning that a human would raise
+the cap and resume. That is true at a terminal and false inside a Kubernetes
+Job, where there is no human: the Job went Complete, the pipeline went green,
+and an incomplete build looked finished. Exit 0 now means the work is finished
+or a person deliberately stopped it -- never that we ran out of money mid-task.
+
+See [exit codes](./exit-codes.md) for the full contract.
+
+## Preview the cost before spending anything
+
+```sh
+loki plan ./prd.md --json
+```
+
+Reports complexity, estimated iterations, token usage and cost **without
+executing**. No provider call, no spend. `LOKI_CONFIG_DUMP=1 loki start ./prd.md`
+prints the resolved configuration and exits, so you can confirm your caps are
+actually set before a real run.
+
+## What you are charged for, stated plainly
+
+Every iteration calls your provider, including iterations spent re-running
+after a quality gate fails. **We do not exempt our own gate failures from your
+budget**, and pretending otherwise would be dishonest -- those calls really do
+consume your tokens.
+
+What we do instead:
+
+- the caps above bound the total, so a doom loop has a hard ceiling
+- the Evidence Receipt records iteration count and cost, so a re-run is visible
+  rather than buried
+- reaching a cap reports as a failure with the reason named, so you know whether
+  to raise the ceiling or narrow the spec
+
+If a run cost more than you expected, `loki proof show <id>` tells you where it
+went.

package/docs/environment-variables.md

@@ -0,0 +1,102 @@
+# Environment variables
+
+The operator-facing knobs, with defaults read from the source rather than from
+memory. Every variable on this page is asserted by a test to still exist, so
+this document cannot quietly rot into fiction.
+
+## What this page is not
+
+The codebase references a few hundred `LOKI_*` tokens. Most are internal
+plumbing between the CLI and the runner (`LOKI_REG_TARGET`,
+`LOKI_CI_JSON_FINDINGS`, and similar), or prefix fragments that are never a
+whole variable. Publishing that number as an "operator surface" would be
+misleading, so this page covers only what an operator would deliberately set.
+
+`loki config schema` lists 64 more keys that map to environment variables and
+can be written to `.loki/config.yaml`. Those are not repeated here. The
+variables below are the ones **not** in that schema -- historically the ones
+with nowhere to look them up.
+
+## Running a build
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_PRD_FILE` | none | Path to a spec file, as an alternative to the positional argument. |
+| `LOKI_MAX_ITERATIONS` | `1000` | Hard cap on iterations. Reaching it is a deterministic terminal failure, not a success. Also in `config schema`. |
+| `LOKI_BUDGET_LIMIT` | unset (no cap) | Spend cap in USD. On exhaustion the run stops and reports a terminal failure -- see [exit codes](./exit-codes.md). |
+| `LOKI_MAX_DURATION` | unset (no cap) | Wall-clock cap in seconds. Stops cleanly at the next iteration boundary with a `max_duration_reached` terminal status. `loki start --max-duration` also accepts `90m` / `2h`. |
+| `LOKI_AUTO_CONFIRM` | unset | `true`/`false` to control prompts. Takes precedence over `CI`. |
+| `LOKI_CONFIG_DUMP` | `0` | `1` prints the resolved configuration and exits **without starting a run or spending anything**. |
+
+For a cost estimate before committing to a run, `loki plan <spec> --json` is
+the better tool: it reports complexity, iterations, tokens and cost without
+executing. See [cost controls](./cost-controls.md) for how the three caps
+interact and why hitting one is a failure rather than a success.
+
+## Choosing a model and provider
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_PROVIDER` | `claude` | `claude`, `cline`, `codex`, or `aider`. |
+| `LOKI_MAX_TIER` | unlimited | Caps model tier, so a run cannot escalate past what you are willing to pay for. |
+| `LOKI_TIER` | per-phase default | Forces a specific tier for the run. |
+| `LOKI_SESSION_MODEL` | provider default | Pins the session model explicitly. |
+| `LOKI_MODEL_OVERRIDE` | unset | Overrides the resolved model outright. |
+
+`LOKI_MAX_TIER` is the cost control worth knowing: it bounds escalation, while
+`LOKI_BUDGET_LIMIT` bounds total spend. They answer different questions and are
+usefully set together.
+
+## Output volume
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error`. |
+| `LOKI_QUIET` | `0` | `1` is shorthand for `warn`. |
+
+**Errors are never suppressed.** `error` is the floor, so even the quietest
+setting still prints failures -- a verbosity control that could hide why a
+build failed would be a footgun. An unrecognized value falls back to `info`
+rather than silencing the run, so a typo in a pipeline config cannot blind you.
+
+Available as flags too: `loki start --quiet`, `loki start --log-level LEVEL`.
+
+Decorative output (the HUD, the completion card, the start headline) already
+suppresses itself when stdout is not a TTY, so CI logs were never the wall of
+banners you might expect. These variables control the remaining `[INFO]` and
+`[STEP]` lines.
+
+## Platform integration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `LOKI_DURABLE_STATE` | `0` | `1` enables durable state **and** the richer process-exit contract that lets Kubernetes distinguish a deterministic failure from a crash. See [exit codes](./exit-codes.md). |
+| `LOKI_SDK_LOOP` | unset | Routes the run through the Bun/TypeScript runner instead of bash. Both implement the same exit contract. |
+
+`LOKI_DURABLE_STATE=1` is the one to set in a Job or task definition. Without
+it every failure collapses to exit 1 and the platform cannot tell "re-running
+this is pointless" from "this crashed and should resume".
+
+## Precedence
+
+Command-line flags beat environment variables, which beat `.loki/config.yaml`,
+which beats `~/.config/loki-mode/config.yaml`.
+
+To see what actually resolved, without starting a run:
+
+```sh
+LOKI_CONFIG_DUMP=1 loki start ./prd.md
+```
+
+## Setting these persistently
+
+`loki config set` writes to the config file for the keys it supports:
+
+```sh
+loki config set budget 25
+loki config set provider claude
+loki config set maxTier sonnet
+```
+
+`loki config schema` lists every key the config file understands, and
+`loki config show` prints the current effective values.

package/docs/exit-codes.md

@@ -0,0 +1,130 @@
+# Exit codes
+
+Every code below was read from the source, not from a help text. If a command
+is absent from this page it returns only the shell defaults (0 on success,
+nonzero on failure) and you should not build a gate on anything finer.
+
+## The one rule
+
+**Severity rises with the code.** `[ $rc -ge 2 ]` always means "worse than the
+level-1 outcome" for any command on this page. If you remember nothing else,
+remember that a bigger number is never better news.
+
+## `loki start`
+
+Two contracts, and which one you get depends on an environment variable. This
+is the part most likely to surprise a script author.
+
+### Default (local, CI)
+
+| Code | Meaning |
+|---|---|
+| 0 | The run completed |
+| nonzero | Something went wrong |
+
+There is no finer signal. A gate that needs to tell "failed the quality gate"
+from "crashed" must opt into the durable contract below.
+
+### With `LOKI_DURABLE_STATE=1` (the platform contract)
+
+Written for a Kubernetes Job, an ECS task, or a systemd unit that has to decide
+whether retrying is worth anything. The distinction it draws is **will running
+this again produce a different result**.
+
+| Code | Meaning | Should the platform retry? |
+|---|---|---|
+| 0 | Completed, or a human stopped it (council approved, completion promise, force-stop, paused, interrupted, stopped) | No. It is done, or a person is driving. |
+| 20 | Deterministic terminal failure (failed a gate, max iterations, max retries, **budget exceeded**, **wall-clock cap reached**, policy blocked, contradictory spec) | **No.** The same inputs fail the same way; a retry only spends money to arrive here again. |
+| any other nonzero | Crash (SIGKILL, eviction, node loss) | Yes. The restarted run resumes from the durable volume. |
+
+`budget_exceeded` sits with the failures deliberately. It used to exit 0 on the
+reasoning that a human would raise the cap and resume, which is true at a
+terminal and false inside a Job: there is no human, so a build stopped mid-work
+by the cost breaker was reported as a success. Exit 0 must mean the work is
+finished or a person chose to stop it.
+
+Helm wires this up for you: `worker.exitCodes.terminalFailure` (default 20)
+feeds the Job's `podFailurePolicy`, so a deterministic failure fails the Job
+immediately instead of burning `backoffLimit`. Requires Kubernetes 1.31+.
+
+Both the bash runner and the Bun runner (`LOKI_SDK_LOOP`) implement this
+identically; a parity test asserts they agree status for status.
+
+## `loki verify`
+
+| Code | Verdict |
+|---|---|
+| 0 | VERIFIED |
+| 1 | CONCERNS (findings below the block threshold, or inconclusive evidence) |
+| 2 | BLOCKED (findings at or above the block threshold) |
+| 3 | Verifier error: it could not complete, and never silently passes |
+
+Code 3 matters more than it looks. A verifier that cannot run is not a pass,
+so `[ $rc -eq 0 ]` is the only safe test for "verified" -- `[ $rc -ne 2 ]`
+would treat a broken verifier as acceptable.
+
+An early draft spec listed `1=BLOCKED, 2=CONCERNS`. That ordering was rejected:
+it is not used anywhere, it has no consumers, and it inverts the
+severity-rises-with-the-code rule that every other command follows.
+
+## `loki ci`
+
+| Code | Meaning |
+|---|---|
+| 0 | Passed, or all findings are below `--fail-on` |
+| 1 | Findings exceed the `--fail-on` threshold |
+| 2 | Error: missing tools or invalid arguments |
+
+Machine-readable output is `--format json` here, not `--json`.
+
+## `loki doctor`
+
+| Code | Meaning |
+|---|---|
+| 0 | Every required check passed. Optional warnings do not fail the command. |
+| nonzero | At least one required check failed; the output names which |
+
+Safe as a preflight gate in an init container or pipeline step:
+
+```sh
+loki doctor || { echo "host is not ready"; exit 1; }
+```
+
+An absent optional provider CLI is a warning, not a blocker, so this will not
+refuse to start over a tool you were never going to use.
+
+## Security scan
+
+| Code | Meaning |
+|---|---|
+| 0 | No high or critical findings |
+| 1 | At least one HIGH |
+| 2 | At least one CRITICAL |
+
+## Signals
+
+`loki start` handles the usual terminating signals conventionally: 130 for
+SIGINT (Ctrl-C), 143 for SIGTERM. Under the durable contract these are crashes
+in the retryable sense -- a pod terminated by the scheduler resumes rather than
+being treated as a completed build.
+
+## Writing a gate
+
+```sh
+# Block a merge unless verification is clean. Note -ne 0, not -eq 2:
+# a verifier ERROR (3) must not pass.
+loki verify || { echo "not verified"; exit 1; }
+
+# Kubernetes: let the platform decide whether to retry.
+LOKI_DURABLE_STATE=1 loki start ./prd.md
+rc=$?
+case $rc in
+  0)  echo "complete" ;;
+  20) echo "terminal failure -- fix the spec or raise the budget, then re-submit" ;;
+  *)  echo "crashed (rc=$rc) -- resume is safe" ;;
+esac
+```
+
+Do not read an exit code through a pipe. `$?` after a pipeline reports the last
+stage, so `loki verify | tee log` gives you `tee`'s status and always looks
+successful. Use `${PIPESTATUS[0]}` in bash, or capture first and test after.

package/docs/image-provenance.md

@@ -0,0 +1,124 @@
+# Verifying the container image
+
+Everything on this page is a command you run against the public registry and
+the public sigstore transparency log. None of it requires an account with us,
+and none of it trusts anything we say here: if a command below fails, the
+correct conclusion is that the image is not what we claim, not that the
+instructions are stale.
+
+## What is covered, and from which version
+
+Read this section before the commands. Provenance that claims more than it
+delivers is worse than none, because it is exactly what an auditor will test.
+
+| Artifact | Signature | SBOM |
+|---|---|---|
+| Container image (`asklokesh/loki-mode`) | first release after v8.5.2 | first release after v8.5.2 |
+| npm tarball (`loki-mode`) | v7.4.10 and later | v7.4.10 and later |
+
+**Images published up to and including v8.5.2 are not signed and have no SBOM.** A signing
+workflow existed from v7.4.10 but was triggered on `release: published`, and
+because our releases are created by a workflow using the default
+`GITHUB_TOKEN`, GitHub never emitted that event. The workflow therefore never
+ran on a real release, which the registry confirms: no `sha256-*.sig` tags
+existed for any version through v8.5.2. Signing now runs inside the same job
+that pushes the image, so it cannot be skipped by a trigger that does not fire.
+
+We are not backfilling signatures for older tags. A signature applied today by
+a different pipeline than the one that built the artifact months ago attests
+to far less than it appears to, and the appearance is the dangerous part.
+
+## Verify the signature
+
+Requires [cosign](https://github.com/sigstore/cosign) v2.x. Substitute your
+version for `8.6.0`.
+
+Signatures are bound to the image **digest**, not to a tag. Tags are mutable --
+`latest` moves every release, and even a version tag can be repointed -- so
+resolve the digest first and verify that.
+
+```sh
+VERSION=8.6.0   # or whichever release first carried signing; see the table above
+DIGEST=$(docker buildx imagetools inspect "asklokesh/loki-mode:${VERSION}" \
+  --format '{{json .Manifest.Digest}}' | tr -d '"')
+echo "$DIGEST"
+
+cosign verify \
+  --certificate-identity-regexp 'https://github.com/asklokesh/loki-mode/.github/workflows/release.yml@.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  "asklokesh/loki-mode@${DIGEST}"
+```
+
+The two `--certificate-*` flags are the part that matters, and omitting them
+is the most common way to get a meaningless pass. Keyless signing means anyone
+with a GitHub account can produce a valid sigstore signature over our image;
+what makes the signature *ours* is that it was issued to our workflow identity
+by GitHub's OIDC issuer. Without those flags cosign will happily confirm that
+the image was signed by somebody.
+
+A pass prints a JSON block including the certificate's subject, which should
+name `release.yml` in this repository.
+
+## Verify and read the SBOM
+
+The SBOM is attached to the image as a CycloneDX attestation. Note this is a
+*separate* artifact from the npm SBOM published on the GitHub Release: the
+image carries an OS layer, a Python runtime and system packages that the npm
+tarball's SBOM never described. If you are deploying by Helm, ECS, or any
+other image-based path, the image SBOM is the one that matches what you run.
+
+```sh
+cosign verify-attestation \
+  --type cyclonedx \
+  --certificate-identity-regexp 'https://github.com/asklokesh/loki-mode/.github/workflows/release.yml@.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  "asklokesh/loki-mode@${DIGEST}" \
+  | jq -r '.payload' | base64 -d | jq '.predicate' > image-sbom.cdx.json
+
+jq '.components | length' image-sbom.cdx.json
+```
+
+`verify-attestation` checks the signature over the SBOM before you read it,
+which is the point: an SBOM you downloaded unverified tells you what someone
+wanted you to believe is in the image.
+
+**Scope limit worth knowing.** We publish a multi-arch image (linux/amd64 and
+linux/arm64). The signature covers the manifest list, so it covers both
+architectures. The SBOM does not: it is generated from a single resolved
+platform, so package versions specific to the other architecture may differ
+from what it lists. If you deploy on arm64 and need an exact bill of materials
+for that architecture, generate it against the arch-specific digest yourself:
+
+```sh
+syft "asklokesh/loki-mode:${VERSION}" --platform linux/arm64 -o cyclonedx-json
+```
+
+Feed `image-sbom.cdx.json` to Grype, Trivy, Dependency-Track or any other
+CycloneDX consumer for CVE scanning.
+
+## Air-gapped environments
+
+Both commands above reach the public sigstore infrastructure (Rekor and
+Fulcio) to check the transparency log. To verify inside an air-gapped network,
+mirror the trust root and the artifacts on a connected host first:
+
+```sh
+cosign save "asklokesh/loki-mode@${DIGEST}" --dir ./loki-image-bundle
+cosign initialize --mirror <your-tuf-mirror> --root <your-root.json>
+```
+
+Then transfer `loki-image-bundle/` and verify with `cosign verify --local-image
+./loki-image-bundle`. See `loki doctor --airgap` for the full host inventory
+the engine itself needs at runtime.
+
+## If verification fails
+
+Do not deploy the image. In order of likelihood:
+
+1. **You verified a tag instead of a digest.** Re-resolve the digest.
+2. **You omitted the `--certificate-*` flags**, verified a digest that was
+   never ours, and got a pass or a confusing mismatch. Both flags are required.
+3. **The version is v8.5.2 or earlier.** See the coverage table above; those images
+   are genuinely unsigned and no command will make them verify.
+4. **The image is not what we published.** Report it at
+   https://github.com/asklokesh/loki-mode/issues and do not run it.