chore: use journeys as prs qa contract

[ovitrif]

Closes #1249

Counterpart: synonymdev/bitkit-ios#743

Description

• Makes #### Journeys the first QA Notes section so that a PR with a user-visible change lists the journeys that prove it, by bare file name with new or updated, and reviewers drive them on a device instead of reading prose.
• Limits #### Manual Tests to steps that need a capability the journey environment lacks, and adds a ## Capabilities table to journeys/README.md as the authority for what it provides, so a step is manual by evidence, not by category.
• Shapes #### Automated Checks as a flat list with added, updated, removed, and ran keywords so the same prefix is never repeated.
• Applies the rules in /pr and states them in AGENTS.md, and lists the android CLI with the android-cli skill under Prerequisites because it is how an agent drives journeys.
• Gives #### Journeys a second empty value, N/A — not drivable; see Manual Tests., for a user-visible change every flow of which needs a capability the journey environment lacks, so BLE pairing and the USB permission flow have a valid value instead of halting /pr.
• Removes the ## Suites listing from journeys/README.md, which was a hand-maintained copy of ls journeys/ that every journey PR had to append to, and states the rule that keeps it gone.

Out of Scope

• journeys/: drift tooling, an identifier index, or a CI check; a journey that fails at review is the drift signal.
• A shared journeys skill giving iOS and Android one driving procedure; each platform names its own driver.
• Past manual tests from merged PRs: kept as a backlog in chore: keep past manual tests as a journeys backlog #1307.

Design

N/A — no UI changes.

Preview

N/A — no user-visible changes.

QA Notes

Journeys

N/A — no user-visible behaviour change.

Manual Tests

N/A

Automated Checks

• ran a per-file diff of the added lines against the counterpart PR: only platform names, test-file types, the driver, and Capabilities rows differ
• ran a diff of the ### QA Notes template section against the counterpart: identical apart from the example test-file name
• ran the review skill's parser tests against the new #### Journeys and #### Automated Checks formats: bare names resolve on the PR head, legacy full paths still parse
• ran every Capabilities row back to the suite README or preconditions section it cites
• ran build, detekt and lint on the PR head: all pass; the e2e workflows skip for a documentation-only diff
• ran a per-file diff of this branch's three changed documentation files against the counterpart PR: byte-identical

[github-actions]

Regtest APK

Built from 587edaf (run).

Download bitkit-dev-debug universal APK (expires in 30 days).

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previous findings are fixed and no actionable new issue remains.

Summary

This PR establishes journeys as the device-driven QA contract for user-visible changes and aligns PR-generation guidance, the pull request template, contributor documentation, and journey capability documentation.

• Adds a required #### Journeys section with checked-at-review journey entries and explicit empty states.
• Restricts manual tests to flows requiring capabilities unavailable to the journey environment.
• Standardizes automated-check descriptions and documents the journey environment’s supported capabilities.
• Removes the manually maintained journey-suite listing.

_{Reviews (3) · Last reviewed commit: "Merge remote-tracking branch 'origin/mas..."}

[jvsena42]

the Journeys readme is causing conflicts on every Pr merge, can we remove it or use something similar to the changeling strategy?

[jvsena42]

One MEDIUM on the QA contract rules (inline). It is docs-only, so it doesn't block. The same gap is on the iOS twin, synonymdev/bitkit-ios#743.

Checked and clean:

• CLAUDE.md→AGENTS.md symlink: the old "not a QA gate" wording is gone everywhere. QA gate and developer-assistance grep clean.
• The Suites table removal leaves no dangling #suites references.
• Every Capabilities link target exists at head.
• pr.md Step 3 discovery and the \.xml$ filter are in place.
• The pr.md structure and style target match the template headings and order.
• The library-repo example's Journeys omission is intentional.

The missing locale/font-scale and run-as rows in Capabilities looked like gaps, but the shell-command rule at journeys/README.md:39 covers them, so I'm not raising them.

[ovitrif]

the Journeys readme is causing conflicts on every Pr merge, can we remove it or use something similar to the changeling strategy?

@jvsena42 Right on the cause, and this PR already removes it — it just never said so, which is why it was not obvious from the diff.

The conflicting part was ## Suites: a table of every suite with its journey count and a note. It was a hand-maintained copy of ls journeys/ — I checked the counts against the tree and they matched exactly — so every PR that added a journey had to append a row, and two PRs adding journeys in the same week conflicted there. That table is deleted here.

What replaces it, ## Capabilities, is a different kind of table. It lists what the environment can provide, not what exists in the corpus, so it changes when we gain or lose a capability, not when someone adds a journey. Adding a journey no longer touches this file at all.

I have added a line to the file saying that, so the listing does not grow back:

It changes when the environment gains or loses a capability, not when a journey is added, so adding a journey does not touch this file. ls journeys/ is the suite list and each suite's README is its own documentation; nothing here restates them.

On the changelog comparison: the reason changelog.d/ works is that each PR writes its own file and nothing edits a shared one. Deleting the suites listing gets the same property here — a journey PR writes its own .xml under its suite and touches nothing shared. A fragment directory would add a collection step for data ls already gives us, so I do not think it earns the machinery in this case. Happy to be argued out of that.

Worth noting this PR hit that conflict five times while it sat open, which is the strongest evidence for the change that I can offer.

[jvsena42]

Delta (71e047ee3): no findings. #### Journeys gets a second empty value for flows the Capabilities table cannot provide, and it requires a matching Manual Tests step. The stop rule no longer fires for BLE or USB-permission-only changes. The README now states that it tracks capabilities, not suites, which answers my conflict question. The master merge 1859b815d resolved the README conflict by dropping master's re-added suite table, which matches the PR's intent. Prose is identical to synonymdev/bitkit-ios#743.

[ovitrif]

Merged master into the branch at 7e2c07e to clear a conflict in journeys/README.md.

• The conflict was the same one as before: master still carried the old ## Suites table in the spot where this branch has ## Capabilities. I kept ## Capabilities and dropped the incoming suite rows.
• Of the suites master added since the last sync, lnurl needs something the table did not list: an LNURL-pay endpoint that accepts comments and issues description-hash invoices. The journey says the staging backend has none, so I added a Capabilities row naming how its setup provides one. send and settings need nothing new.

The branch still changes only the same four documentation files against master.

[ovitrif]

Correction at 501f71a to the LNURL row I added in the previous push.

That row called LNURL unavailable except through a custom lnurl-node server, which was wrong. I had taken the claim from the lnurl journey, where it applies to one check only. The bitkit-docker lnurl-server covers LNURL pay, withdraw, channel and auth, plus Lightning Addresses, and just run docker points the app at it. The row now names that setup, with one limit: the server issues memo invoices, so a check that needs a description-hash invoice (such as the lnurl journey's) needs a different endpoint.

[ovitrif]

Merged master into the branch at b52a57d to clear another journeys/README.md conflict. This merge also restores four Cross-platform rows that my 7e2c07e merge dropped.

• The conflict was the usual one: master added an app-update row to its ## Suites table, and this branch replaces that table with ## Capabilities. I dropped the Suites row. app-update needs a local build change and a feed file that the journey itself describes. That is setup for one journey, not something the environment provides, so it needs no Capabilities row.
• In the Cross-platform table, 7e2c07e kept only this branch's side of the file, which dropped four rows master had added: amount-limits/transfer-spending-preset-delete.xml, send/own-invoice-guard.xml, settings/electrum-server-error-toasts.xml and lnurl/lnurl-pay-comment-note.xml. This merge takes that table from master, which restores those four and adds the new app-update row.

journeys/README.md now differs from master only in this PR's intended changes. I checked every earlier merge on this branch and on the iOS counterpart, and none dropped anything else.

[jvsena42]

Delta since 71e047ee3 (501f71af1): no findings. The LNURL row now describes the bitkit-docker lnurl-server reached through just run docker, which exists in the Justfile and does the adb reverse forwarding the row claims. The memo-invoice caveat is kept, so the description-hash gap stays recorded.

[jvsena42]

Approved with one suggestion

[ovitrif]

Merged master at be3546c to clear the recurring journeys/README.md conflict. It was the same hunk as before: master's ## Suites table against this branch's ## Capabilities. I kept Capabilities and took master everywhere else. The new security/pin-lock-on-resume.xml journey needs nothing the table doesn't already list. The PR still changes only its four documentation files. It needs a fresh approval on this head.

[ovitrif]

Merged master at 587edaf to clear the journeys/README.md conflict: master's ## Suites table against this branch's ## Capabilities. I kept Capabilities and took master everywhere else. The new coin-selection/manual-coin-selection-load.xml only needs on-chain UTXOs, which the table already lists. The PR still changes only its four documentation files. It needs a fresh approval on this head.