chore: use journeys as prs qa contract

[ovitrif]

Closes #742

Counterpart: synonymdev/bitkit-android#1250

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 xcodebuildmcp CLI under Prerequisites because it is how an agent drives the simulator through 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 #763.

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 validate, Run Tests and Run Integration Tests 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

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable correctness, security, or repository-rule issues remain.

Summary

This PR makes journey files the primary QA contract for user-visible changes and aligns the PR-generation command, pull-request template, contributor guidance, and journey documentation around that process.

• Lists only added or updated journey XML files, using unchecked reviewer-owned checkboxes.
• Reserves manual testing for capabilities absent from the documented journey environment.
• Standardizes automated-check descriptions and documents the available journey capabilities.
• Removes the duplicated suite inventory from the journey README.
• The previous finding about non-XML files appearing as journeys is fixed by filtering the discovery command to names ending in .xml.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Inspect PR changes] --> B{User-visible behavior?}
    B -- No --> C[Journeys: N/A — no user-visible behaviour change]
    B -- Yes --> D{Flow supported by Capabilities?}
    D -- Yes --> E[Add or update journey XML]
    E --> F[List unchecked journey in PR]
    D -- No --> G[List unchecked Manual Test with missing capability]
    G --> H{Any supported flows?}
    H -- No --> I[Journeys: N/A — not drivable; see Manual Tests]
    H -- Yes --> E

Loading

_{Reviews (3) · Last reviewed commit: "chore: allow a not-drivable journeys val..."}

[jvsena42]

One MEDIUM and one LOW (inline). Both are docs-only, so they don't block. The MEDIUM is shared with the Android twin, synonymdev/bitkit-android#1250.

Checked and clean:

• The added pr.md and template lines match Android apart from test-file naming and the View/Screen suffix.
• The AGENTS.md QA-contract bullet matches Android.
• The "not a QA gate" wording and the #suites anchor are removed with no dangling references.
• Capability link targets exist.
• The to.bitkit bundle id in the simctl uninstall row matches pbxproj.
• The missing UTXO and deep-link-router rows are platform-forced.
• \.xml$ discovery filter present.

[ovitrif]

Pushed 1526fa8c, mirroring bitkit-android#1250, and marked this ready for review.

• #### Journeys gains a second empty value, N/A — not drivable; see Manual Tests., for a user-visible change whose every flow needs a capability the journey environment lacks. It requires a matching step under #### Manual Tests, and the stop rule no longer fires for those flows. In .agents/commands/pr.md and the PR template.
• journeys/README.md now states that the Capabilities table tracks capabilities rather than journeys, so adding a journey never touches the file. That is the answer to the merge-conflict question raised here and on the Android counterpart.

The description is updated to match: two new Description bullets and the automated checks this run actually covered. The diff against master is four documentation files and no app code.

Undrafting started the unit and integration suites that were skipping while this was a draft; validate, detect-changes and e2e-status pass on this head.

[jvsena42]

Delta (1526fa8c): 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. Prose is identical to synonymdev/bitkit-android#1250.

[ovitrif]

Added an LNURL row to the Capabilities table in journeys/README.md at 95bb211.

The bitkit-docker lnurl-server covers LNURL pay, withdraw, channel and auth, plus Lightning Addresses. A simulator build with E2E_BUILD reaches it by default. The table did not list it, so LNURL steps would have been wrongly classed as manual. The row notes one limit: the server issues memo invoices, so a check that needs a description-hash invoice needs a different endpoint. The Android counterpart has the matching row.

[jvsena42]

Delta since 1526fa8c (95bb2119): no findings. The new LNURL capability row matches the build flags in the repo: E2E_BUILD with E2E_BACKEND defaulting to local, as AGENTS.md describes. Same caveat as the android twin about memo invoices.

One deliberate difference from synonymdev/bitkit-android#1250: android replaces its old description-hash row, while this adds a new row and keeps no — [lnurl] suite link, since iOS has no lnurl suite. That reads correctly.

[jvsena42]

Approved with a suggestion

[ovitrif]

Merged master at 3a6b844 to clear the journeys/README.md conflict: master's ## Suites table against this branch's ## Capabilities. master added deeplinks/pubky-contact.xml, which opens bitkit://contact?pubky=, so I added that route and the deeplinks link to the existing deep-links Capabilities row. The PR still changes only its four documentation files. It needs a fresh approval on this head.