firehose/AGENTS.md

# Agent Instructions

This project has a *zero defects policy*. 
When you are unsure about something, ALWAYS ask the user.

# Communication

When creating yaks or working on features, always ask clarifying questions to ensure understanding. Ask questions one at a time to maintain clear communication and allow for focused discussion.


You run in a `nono` sandbox. Always ask the user to run commands that require privilege, like docker, sudo or package installation.

# Repository structure

This is an Elixir monorepo with two parts:

```
firehose/
├── app/                    # Phoenix application (OTP app: :firehose)
│   ├── lib/firehose/       # Application logic
│   ├── lib/firehose_web/   # Web layer (controllers, live views, components)
│   ├── lib/firehose/blogs/ # Blog definitions (engineering, release notes)
│   ├── priv/blog/          # Markdown posts
│   └── mix.exs
├── blogex/                 # Blogex library (multi-blog engine)
│   ├── lib/
│   └── mix.exs
├── mise.toml               # Runtime versions (Elixir, Erlang, Node)
├── Dockerfile              # Deploy build; ARG pins must match mise.toml
├── scripts/check-pins.sh   # Verifies the pin sync; runs in `make check`
├── .githooks/pre-push      # Lens pass on push; install once with `make hooks`
└── Makefile                # make (check, verify, test, hooks)
```

Two blogs are configured:

# Toolchain pins

`mise.toml` and the `Dockerfile` ARG pins must agree; `scripts/check-pins.sh`
(runs as part of `make check`) enforces this. When bumping versions, change
both files in one commit. Upstream drift (newer Elixir/OTP/Debian releases)
is reported by `dokku-updates firehose check` (dokku-maintenance repo).
Upgrading pins or mix packages is largely unscripted: for such tasks, a Pi
sub agent can be started in this directory — it reads this AGENTS.md and
follows the zero-defects policy above.

| Blog | Route | Description |
|------|-------|-------------|
| Engineering | `/blog/engineering` | Main blog | 
| Release Notes | `/blog/releases` | What's new in an app |

# Permissions

ALWAYS ask the user for permission when you want to add a fallback, or are unsure something work. The user can perform exploratory testing.

We have a zero defects policy, so never continue when there are errors, warnings or test failures, even when they are pre-existing. ALWAYS report these to the user and discuss an action plan with root cause analysis. (see TDD below).

# Planning

we use  `yx` for planning run yx --help to see options. Invoke when the user wants to make a plan, work on something for a plan or mentions 'yak' or 'yaks'.

`yx list` - shows open yaks
`yx add` - adds yaks
`yx context "yak name"` - adds human-readable description (pipe via stdin)
`yx show "yak name"` - shows yak details including context

# Building

This is a Phoenix Liveview monorepo, the blogging library is in blogex, the application is in 'app'. Use `make` to build and `brief` to find out more about mix. 

Main make targets:

- `make setup` - one-time clone setup (and after any mix.exs gains a dep):
  fetches Hex deps for both apps and the app's JS packages. Needs network -
  run it yourself; agent sandboxes refuse installs. check/test/verify never
  touch the network: they run a local `deps.check` guard that fails with a
  pointer here when deps are missing.
- `make check` - cheap static gate for both apps (no DB): app `credo --strict` +
  format **check** (`mix format --check-formatted`), blogex compile (warnings
  fatal) + format **check**, then `scripts/check-pins.sh`. It never rewrites
  files.
- `make precommit` - alias of `check`; fast, safe to run on every commit
- `make test` - both suites (app needs PostgreSQL on localhost:5432)
- `make verify` - the Lens pass: `check`, then per-app heavy sensors and both suites
- `make hooks` - install `.githooks/*` into this clone (once per clone)

# Verification: fast loop vs Lens pass

Two loops, deliberately split so commits stay cheap and pushes stay honest.

**Fast loop (every commit).** `make check` is static analysis only: no database,
no coverage, about a second. `make precommit` is the same target. Per app,
`mix precommit` (run inside `app/` or `blogex/`) is the fuller loop: compile with
warnings fatal, format, test. Run these as often as you like while working.

`make check` never writes files. A formatting failure means run `make format`
(both apps). The mutating loops are the explicit ones: `make format` and the
per-app `mix precommit`, which still formats as you work.

**Lens pass (every push, and before handing off).** `make verify` runs `check`
first (cheapest), then per app: one suite run that exports its coverage, then
that app's sensors (sobelow, coverage, CRAP; mutation as that yak lands), which
run cheapest-first and read the export rather than re-running the suite. Measured
2026-11-01: ~11s wall (app 178 tests + blogex 156 tests + coverage floor).

`.githooks/pre-push` runs `make verify` and blocks the push when anything fails.
Install it once per clone:

    make hooks

It symlinks `.githooks/*` into the clone's hooks directory; `core.hooksPath` is
deliberately left alone so bd's own hooks (pre-commit JSONL flush, post-merge
import) keep firing. On failure the hook prints one summary - last step started,
log path, bypass - and exits non-zero; the full output is in `.git/lens-pass.log`.
Deliberate override (e.g. pushing a branch you know is red): `git push --no-verify`.

## Lens practice

The Lens pass is a *separate pass with its own context*. It is not a way to find
work mid-feature: finish and commit what you are building, then run it.

- Do not chase hook or `credo` output inline while building a feature. If
  something interesting surfaces, note it and file a yak; take it up in a Lens
  session.
- A failing Lens pass blocks the push, and therefore the hand-off. Triage it;
  never re-run until green and never ignore it.
- Adding a sensor: implement it as its own make target, add it to that app's
  `VERIFY_SENSORS` in `app/Makefile` / `blogex/Makefile` (cheapest first), and
  update the slot comments there. A gate that reports a check it did not run is
  worse than no gate - the `VERIFY_SENSORS` list is what gets echoed. Sensors run
  *after* the app's `test.coverage` step, because the coverage export they read is
  produced by that suite run; if a check can pass without its input, make it fail
  loudly (see the `coverage` target's guard).

### Triage classes

| Class | Looks like | What to do |
|-------|-----------|------------|
| *Real bug* | behavior is wrong; a test fails for a real reason; a sensor reports a real risk | fix inline, with a test that pins the behavior |
| *Environment-dependent test* | passes alone, fails in the pass; depends on ambient state (rows left behind, wall clock, ordering, network, locale) | the test is the bug: make it deterministic by construction - own fixtures, explicit clock, no ambient state as fixtures. Never retry-until-green |
| *Style or design nit* | credo or format suggestion, naming, structure, "this could be smaller" | do not refactor mid-build: note it and file a yak; the Lens session decides |

Reconciling this with the zero-defects policy: "never continue when there are
errors" governs *what you do with a failure* - report, triage, decide - not
*when* you fix it. Never silently absorb a finding, and never let a pre-existing
failure ride along: if it predates your change, stop and discuss it with the user
rather than working around it.

Browser tests (`make playwright*`) are *external* verification and are **not**
part of the Lens pass. Decided 2026-10-28 (human, yak "ratchets, deferred
decisions, handoff practice"): it stays that way - Playwright is not wired into
`make verify` or into either `VERIFY_SENSORS`. The targets need a running
Phoenix server or the Docker Chrome container, and a gate that only runs with
docker or sudo is not a gate the Lens pass can rely on. Run them as their own
loop, by hand, when a change touches the browser surface.

### Landing the plane

The Lens pass is what you land with, so it is the last step of every session,
not a thing that only happens on push:

- After any session that changed code, run `make precommit`. It is `make check`
  under its session-ending name and costs about a second; there is no session
  where it is not worth running.
- Before handing off - to a human, a reviewer, or the next agent - run
  `make verify`, or push, which fires `.githooks/pre-push` and runs the same
  pass on the same tree. A hand-off note that says "tests pass" without a Lens
  pass behind it is a guess, not a hand-off.
- A failing Lens pass is triaged into the classes above (see *Triage classes*)
  and **reported** in the hand-off note, with the class it fell in. A nit gets a
  yak; it does not get fixed inline mid-build. Never re-run until green.
- `git push --no-verify` stays the deliberate override for a branch you know is
  red. It is never how a session lands.

## Ratchets

The coverage threshold in `app/mix.exs` and `blogex/mix.exs` (the `threshold:`
inside each `test_coverage/0`) is a **floor**, not a target:

- After each behavior-test yak lands, re-measure both apps - `make test.coverage`
  then `make coverage` inside each app - and raise the floor to the new total.
  The convention is integer truncation of the measurement: a measured 82.61%
  means a floor of 82. Never above the measurement: a floor that cannot pass is
  not a ratchet, it is a red gate.
- Never lower a floor. A legitimate drop is a conversation, not a config edit.
  Lowering the number, or adding an `ignore_modules` entry to prop it up, hides
  the behavior gap the floor exists to surface.
- The record of the last measurement and its date is the comment above
  `test_coverage/0` in that app's `mix.exs`. Update it there, in the same commit
  as the number. Do not copy the totals into this file: one record, in the
  place the gate reads, is the whole point.

Two further health numbers are baselines-to-be; neither is `make verify`'s
business yet, and neither is to be invented:

- **CRAP offender count.** `make crap` in one app is the sensor: a passing run
  prints `Summary: ... worst_score=...`, a failing run prints `High scores: N`
  and the offending functions. Both apps sit under the default `--max-score
  (30)`, and the decision (2026-10-28) not to lower it, plus the baseline
  offender count, live in the comment above the `crap` target in
  `app/Makefile` / `blogex/Makefile`.
- **Mutation survivor count.** Mutation is a slot comment only in
  `app/Makefile` and `blogex/Makefile` ("yak: mutation testing with muex - a
  sensor, not a gate"), and `muex` is a dependency of neither app. Nothing has
  been mutated, so there is no survivor baseline; do not conjure one from a run
  that did not happen. When the mutation yak lands, its survivors become the
  baseline the same way the coverage floor did: measured, dated, recorded where
  the sensor lives.

# Development
Always fix failing tests, credo issues and format isseus.

When developing new features, we apply TDD. Work Test-First, and Refactor when all tests are passing.

If you believe an issue is pre-existing, stop work, and have a conversation with the user on how to address the pre-existing issue, as well as how to prevent this in the future.