archy/AGENTS.md

# Blocking incident: Framework LND startup and false zero balance

Before starting or resuming work in this repository, read
`docs/incident-framework-lnd-startup.md` and check its status.

The user explicitly required this incident to take priority over later work.
While its status is OPEN:

- Surface this blocker at session start, including when the user asks for unrelated work.
- Prioritize investigation and repair on the actual Framework node. If access is
  unavailable, ask for it and continue useful offline investigation; defer unrelated
  work unless the user explicitly overrides this priority.
- A manual LND restart, a source patch, passing local tests, or publishing an OTA
  does not resolve the incident. Do not mark it fixed until the Framework's startup,
  Receive flow, and balance behavior are verified on the node, including a controlled
  reboot with access and recovery arrangements in place.
- Preserve wallet identity, wallet/channel databases, credentials, and backups.
  Never run wallet wipe/recreation as an automatic investigation or recovery step.
- Record evidence, changes, validation, and remaining work in the incident document.

This priority comes from the user's explicit instruction on 2026-09-15. It remains
in effect across sessions until the documented acceptance criteria are met or the
user explicitly changes it.

## Unit tests on a live node

Run backend unit tests through `scripts/test-backend-isolated.sh`. Do not run
unrestricted `cargo test` on a node with installed apps: older mocked-runtime
tests still reached real service commands. The runner isolates wallet data,
service buses, container storage, networking, and process IDs. Compilation with
`cargo test --no-run` is safe. Keep separately authorized live checks explicit.

## Active release regression checklist

Before resuming release work, read
`docs/post-1.8.22-regressions-20261001.md` and retain its unfinished tasks.
The operator requested that every reported issue be tracked, fixed and tested
before another OTA/ISO. Keep source/unit-test results separate from actual-node
acceptance. In particular, paid-file recovery must not send another payment,
and app cleanup must preserve wallets, persistent data and uninstall decisions.
Do not mark the new paid-file incident resolved merely because the earlier
Framework LND startup incident was closed.

## Gitea and ngit mirror parity

Nostr Git (`ngit`) is the canonical contribution and review platform. Gitea
(`origin`) mirrors accepted code on `main` and release tags. Both are required
publication mirrors; duplicate PRs and proposal branches on Gitea are not required.
For every change, including fixes and release preparation:

- Review and merge once. Push the exact same resulting commits to both mirrors;
  never independently squash, rebase or merge the same change on each platform.
- Open new contributions and PRs on ngit; review and merge there, then mirror the
  exact accepted main commits to Gitea. Record the ngit proposal and resulting
  merge commit in the release ledger. Existing Gitea PRs must be reviewed and
  explicitly linked to their ngit replacement or accepted result before closing;
  do not abandon contributions or mark unmerged changes as merged. PR numbers,
  reviews and discussions remain platform-specific; matching Git refs does not
  prove their synchronization.
- Push main and release tags to both mirrors. Preserve commit history
  and annotated tag objects/signatures. Do not resolve drift by force pushing,
  deleting remote refs, or rewriting published history without explicit approval.
- After publishing source, run `python3 scripts/check-git-mirrors.py --local`.
  Include each additional shared branch or release tag with repeated `--ref`
  arguments (full `refs/heads/...` or `refs/tags/...` names).
- Before OTA, catalog or ISO publication, require matching reviewed local and
  remote main and release tag refs, and record ngit PR dispositions in the
  release acceptance ledger. A failed push, unavailable mirror, missing ref or
  mismatch blocks publication; never describe a partial push as synchronized.
  Run `--all` for a complete advertised branch/tag audit; a main-only pass must
  never be described as full historical mirror parity. Proposal-only branches
  may intentionally differ. Existing unrelated drift
  must be inventoried explicitly rather than silently overwritten.