Enforce cross-SDK feature parity with an SDK development spec and a PR check

[brionmario]

Problem

A ThunderID feature is almost never a single SDK change. The same capability has to exist in
javascript-sdks, ios-sdks, android-sdks and flutter-sdks before a developer can rely on it,
but nothing in the current process forces that to happen.

In practice features land first in the SDK that is under active use (usually React in
javascript-sdks), and the sibling SDKs fall behind silently. There is no artifact that says what
an SDK must implement, and no signal at PR time asking "does this need to ship in the other SDKs
too?". Parity gaps are discovered reactively, by a developer hitting a missing capability on
Mobile, long after the feature shipped on web.

Now that the SDKs live in separate repositories, a reviewer of a javascript-sdks PR has no
visibility into whether the equivalent iOS, Android and Flutter work exists, is planned, or was
consciously skipped. Tracking this by convention alone has not worked.

Related to spec driven development proposal in #3292.

Corresponding feature:

• Define a process to ensure feature parity across ThunderID SDKs #5305

Proposal

Two parts: write the contract down, then enforce it with a check.

1. An SDK development spec in docs-internals

Following the design workflow introduced in
docs-internals, add:

docs-internals/sdk-development/
└── spec.md

The spec defines what every ThunderID SDK must honour and what "done" means for an SDK change:

• The canonical surface every SDK implements: flows, configuration shape, session and token
  lifecycle, error taxonomy, naming conventions, and the platform specific deviations that are
  allowed.
• The delivery rule: a feature or breaking change in one SDK repo is not done until an
  equivalent PR exists in every SDK repo where the capability applies, or the omission is
  recorded with a reason.
• What counts as "does not apply", for example a browser only capability that has no meaning on
  Mobile, or a platform that has no equivalent primitive yet.
• The parity record itself: where the cross SDK status of a capability is tracked so the gaps
  are visible without reading four changelogs.

Since specs now live in docs-internals, the SDK spec is reviewed as its own pull request in the
product repo before the implementation work starts, and updates to it follow the same path.

2. A static check that enforces cross SDK PRs

Add a required check to every SDK repo, ideally as one reusable workflow in thunder-id/.github
called by javascript-sdks, ios-sdks, android-sdks and flutter-sdks.

How it behaves on a PR that touches SDK source:

1. The check reads a dedicated section of the PR body, for example:

   ## SDK parity
   
   - [x] thunder-id/ios-sdks#412
   - [x] thunder-id/android-sdks#233
   - [ ] flutter-sdks: not applicable, Flutter wraps the native SDKs and needs no change

2. If the section contains at least one linked SDK PR, or a written reason why the other SDKs do
   not need one, the check passes and applies a single label: sdk-parity-reviewed.

3. If neither is present, the check fails and the bot posts a comment naming the sibling repos,
   linking the spec, and explaining that the author must either link the corresponding PRs or
   state why they are not needed.

4. The check re-runs on edited and on label changes, so the author clears it by editing the PR
   body rather than pushing an empty commit.

One label keeps this legible. sdk-parity-reviewed means "somebody has answered the parity
question on this PR", nothing more, and its absence on a merged PR is the thing worth auditing.
A maintainer applying it by hand is also the escape hatch when the heuristics get a PR wrong.
Beyond that, skip the check entirely for PRs labelled chore, ci, docs or dependencies.

Benefits

• A feature shipped in one SDK is either shipped everywhere it applies, or has a recorded and
  searchable reason why not.
• Reviewers see the cross SDK picture on the PR they are reviewing, instead of trusting that
  someone remembered.
• New SDKs and AI assisted implementations have a single contract to build against, which is what
  Adopt Spec-Driven Development for ThunderID #3292 is aiming for.
• The reasoning lives on the PR itself, so a merged PR without sdk-parity-reviewed is an easy
  query and becomes the backlog for the next parity pass.

Open questions

• Does the parity record belong in the spec itself, in a generated matrix, or in a tracking issue
  per capability?
• Should the check be advisory (soft fail) for the first few weeks so we can tune it before making
  it required?
• Which path patterns should trigger the check per repo, so sample apps and docs only changes do
  not get flagged?
• Do we want the check to auto open draft issues in the sibling repos when parity is deferred, or
  keep that manual?

[brionmario]

Update (Phase 01)

The SDK development spec from this proposal is in, and the four SDK repositories now point at it.

#5367 adds, under docs-internals/sdk-development/:

• spec.md, the contract every ThunderID SDK implements: the layer model and dependency rules, per platform packaging and build, integration packages, the two operational modes, configuration keys, the client surface, framework integration, the UI component contract, i18n and theming, the error model, the security floor, cross SDK parity and delivery, repository layout and CI, testing, docs and samples, with eight requirements carrying acceptance criteria.
• threat-model.md, the SDK modelled as a public client holding the user's tokens in a runtime we do not control, across five interactions. The security floor in the spec comes from it.
• .agent/skills/sdk-development/SKILL.md, the skill that loads both and drives a change through to raised pull requests. It holds no contract of its own, so it cannot drift from the spec.

The draft that existed before was not ported as is. Every claim in it was checked against the four SDK repositories as they stand today and the parts that no longer held were rewritten: the repository topology after the split, the explicit mode key, the real ThunderIDError hierarchy, the dev.thunderid Android coordinates, the actual package list, and the mobile build model the draft never worked through.

The same AGENTS.md section, worded identically, then went into each SDK repository, linking to the spec rather than copying it:

• Point agent instructions at the SDK development specification javascript-sdks#98
• Point agent instructions at the SDK development specification ios-sdks#22
• Point agent instructions at the SDK development specification android-sdks#28
• Point agent instructions at the SDK development specification flutter-sdks#35

On parity specifically, the spec now states the delivery rule: a capability is delivered once it exists in every SDK where it applies, or its absence is recorded with a reason; a pull request changing an SDK's public surface either links the sibling pull requests or says why they are not needed; "no time" is a deferral recorded as a tracked issue, not a reason; dependency, CI, docs, test and refactor changes are exempt; and existing divergences go through the normal backlog rather than being reconciled retroactively.

Tracking issue: #5305.