github/self
1
1
Fork 0
mirror of https://github.com/selfxyz/self.git synced 2026-04-27 03:01:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update specs to be agentic (#1811)

Browse Source 
* save chunk 1e work

* chunk 2f

* pr feedback

* fix pr feedback

* cr feedback

* remove dupe var

* feedback from cr

* add kmp:start dx helper

* save web consolidtion work for later

* add specs

* update

* pr fixes

* update reorg plan

* add coverage gaps spec

* pr feedback

* save current wip iteration

* finalize spec work
This commit is contained in:
Justin Hernandez
2026-03-05 16:20:46 -08:00
committed by GitHub
parent 44ded24886
commit a367e7eecb
37 changed files with 1866 additions and 1098 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
AGENTS.md
View File

@@ -46,6 +46,7 @@ Before creating a PR, ensure:
- [ ] PR description includes context for AI reviewers
- [ ] Complex changes have inline comments explaining intent
- [ ] Security-sensitive changes flagged for special review
- [ ] Review/spec text is signal-only: remove non-actionable praise, back-patting, and generic commentary; keep concrete issues, risks, decisions, owners, next steps, and validation evidence
#### Follow-up Planning
@@ -206,18 +207,27 @@ These workspace-specific files override or extend the root instructions for thei
The `specs/` folder contains architecture and implementation specs for the Self SDK project (WebView engine + native shells). These specs are designed to serve as both human documentation and AI agent prompts.
### Spec Structure & Naming Rules
- Do not create one-file folders. If a folder would contain only one markdown file, keep that file at the parent project level.
- File names should describe doc type, not repeat project name when already inside the project folder.
- Preferred project-level names: `INDEX.md`, `OVERVIEW.md`, `PLAN.md`, `STATUS.md`, `HANDOFF.md`, `REVIEW.md`, `ARCHITECTURE.md`, `INITIATIVE.md`.
- `INDEX.md` is navigation only (entrypoint/table of contents for that folder).
- `OVERVIEW.md` is substantive context (architecture/scope/status summary), not just a link list.
- Do not use `INDEX.md` and `OVERVIEW.md` as synonyms for the same purpose.
- Workstream docs under `workstreams/<scope>/` use `SPEC.md` (context + implementation in one file).
- Use suffixed variants (for example `SPEC-<TOPIC>.md`) only when multiple specs of the same type are required in the same folder.
- When renaming/moving spec files, update all references in `specs/`, `AGENTS.md`, and `CLAUDE.md` in the same change.
**Start here:** [specs/README.md](./specs/README.md) — table of contents and reading order.
Key files:
- `specs/SDK-OVERVIEW.md` — Architecture, bridge protocol, module table, decision matrix
- `specs/WAVE-PLAN.md` — Dependency-ordered execution plan for parallel agent work
- `specs/SPEC-GUIDE.md` — How to write specs
- `specs/PROJECT-RULES.md` — Project-specific rules and guardrails
- `specs/person*/OVERVIEW.md` — Workstream orientation (what you own, dependencies)
- `specs/person*/SPEC.md` — Implementation details (chunks, code changes, I/O examples)
- `specs/projects/sdk/INDEX.md` — SDK project entry point, workstream links
- `specs/projects/sdk/OVERVIEW.md` — Architecture, bridge protocol, module table, execution status
- `specs/projects/sdk/workstreams/*/SPEC.md` — Implementation details (chunks, code changes, I/O examples)
**Before implementing SDK work:** Read `specs/PROJECT-RULES.md` and the relevant workstream's `SPEC.md`. These specs contain explicit constraints ("You will NOT..."), validation commands, and file ownership boundaries that prevent common mistakes.
**Before implementing SDK work:** Read `CLAUDE.md` Key Rules and the relevant workstream `SPEC.md` under `specs/projects/sdk/workstreams/`. These specs contain explicit constraints ("You will NOT..."), validation commands, and file ownership boundaries that prevent common mistakes.
## Scope

59
CLAUDE.md
View File

@@ -26,9 +26,22 @@ nvm use && corepack enable && yarn install
- **Native handlers are thin wrappers.** No business logic in Kotlin or Swift. All logic lives in TypeScript.
- **Keychain is always native-managed.** No web fallbacks for secure storage. This is a security boundary.
- **No “slop comments.”** Only add comments when they convey non-obvious intent or constraints. Never add generic or chatty comments.
- **Signal over praise in docs/reviews.** Remove feel-good or back-patting text that does not change decisions or actions. Keep only actionable content: concrete issues, risks, decisions, owners, next steps, and validation evidence.
- **Spec naming and structure must be context-first.** Use doc-type file names (for example `OVERVIEW.md`, `SPEC.md`) and do not repeat project prefixes in file names. Use descriptive labels in markdown links — `[SDK Overview](./OVERVIEW.md)` not `[OVERVIEW.md](./OVERVIEW.md)` — so the link text is meaningful without folder context.
- **No singleton spec folders.** Do not create a folder that exists only to hold one markdown file; keep single docs at the nearest meaningful project/shared root.
- **Workstream spec names are fixed.** Under `workstreams/<scope>/`, use `SPEC.md` (context + implementation in one file); use `SPEC-<TOPIC>.md` only when multiple implementation specs are needed in that same folder.
- **Test value over mock wiring.** Prefer tests that validate behavior. Avoid tests that only assert mocks were called unless that is the behavior being validated.
- **PR size target:** 1k–3k LOC changed. Smaller is fine for focused fixes. If >3k, add a brief justification for why it can’t be split.
- **No generated artifacts in source PRs.** Do not commit build outputs or generated assets unless the build system requires them for runtime or distribution.
- **Each chunk = one PR.** Don't bundle chunks into mega PRs. Keeps reviews fast, reverts clean, and progress visible.
- **TypeScript is the primary surface area.** All core logic (proving machine, state machines, stores, UI) lives in TypeScript in the WebView. Kotlin and Swift exist only for hardware access (NFC, camera, biometrics), OS-level APIs (keychain, lifecycle), and crypto signing/key-gen. Before writing any native code, ask: "Can this run in the WebView?" If yes or maybe, it belongs in TypeScript.
- **Maximize code reuse through `mobile-sdk-alpha`.** Before adding code to `webview-app`, `kmp-sdk`, or `app/`, check if `mobile-sdk-alpha` already has it or should have it. Types, interfaces, constants, parsing, validation, formatting, state machines, and stores belong in the SDK. Migrate shared code to `mobile-sdk-alpha` before building WebView UI that needs it.
- **Bridge protocol is the only coupling.** Native shells and the WebView share a JSON contract, not code. New native handlers must follow the bridge protocol exactly — no custom messaging, no side channels, no platform-specific extensions. The WebView must not know which native shell it's running inside.
- **Adapter interfaces are the coupling layer.** WebView code imports adapter interfaces from SDK core. Native shells implement bridge handlers. Nobody imports code across the bridge boundary.
- **Fail closed on security-critical boundaries.** Default-deny for protocol compatibility, remote bundle loading, and verification session lifecycle. Reject unknown protocol versions, block remote `devServerUrl` in production.
- **No regressions in the RN app.** Every change to `mobile-sdk-alpha` must be backwards-compatible with the existing Self Wallet app.
- **Specs stay current.** When implementation deviates from the spec, update the spec. A stale spec is worse than no spec.
- **Constraint tie-breaker.** If rules conflict: correctness and security first, then scope/clarity (small PRs, small files), then reuse. Document the tradeoff in the spec.
## Specs & Planning
@@ -36,29 +49,45 @@ nvm use && corepack enable && yarn install
### Spec System (`specs/`)
| File | Purpose | When to Read |
| -------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------ |
| [README.md](./specs/README.md) | Table of contents, reading order | First. Always. |
| [SPEC-GUIDE.md](./specs/SPEC-GUIDE.md) | How to write specs (three-tier system, review checklist, AI agent guidelines) | Before writing or reviewing any spec |
| [TEMPLATES.md](./specs/TEMPLATES.md) | Copy-paste templates for all three tiers | When creating a new spec |
| [PROJECT-RULES.md](./specs/PROJECT-RULES.md) | Project-specific rules and guardrails | Before starting any implementation work |
| [SDK-OVERVIEW.md](./specs/SDK-OVERVIEW.md) | Architecture, bridge protocol, module table, decision matrix | For system-level context |
| [WAVE-PLAN.md](./specs/WAVE-PLAN.md) | Dependency-ordered execution plan | When planning which chunks to execute next |
| File | Purpose | When to Read |
| ------------------------------------------------ | ------------------------------------------- | ------------------------ |
| [Specs README](./specs/README.md) | Table of contents, reading order | First. Always. |
| [Templates](./specs/framework/TEMPLATES.md) | Copy-paste templates for all three tiers | When creating a new spec |
| [SDK Overview](./specs/projects/sdk/OVERVIEW.md) | Architecture, bridge protocol, module table | For system-level context |
Workstream specs live in `specs/person*-*/` with `OVERVIEW.md` (stable orientation) and `SPEC.md` (living implementation details).
Workstream specs live in `specs/projects/sdk/workstreams/*/` with `SPEC.md` (living implementation details).
### Spec-Reading Protocol (for chunk execution)
To execute a chunk:
1. Read `specs/projects/sdk/INDEX.md` — find your workstream
2. Read the workstream `SPEC.md` — find your chunk
3. If you need architecture context, read the project `OVERVIEW.md`
That's it. Do not read framework docs unless you are writing a new spec.
### Planning Protocol
1. **Read** `specs/PROJECT-RULES.md` and the relevant workstream specs — understand the current state and constraints
2. **Write a plan to disk** — use the appropriate tier from `specs/TEMPLATES.md`:
- **Large features / new workstreams:** Create a full implementation spec (`specs/person-scope/SPEC.md`)
- **Medium features / multi-chunk work:** Create a session plan file in `specs/` or update the relevant SPEC.md
1. **Read** the relevant workstream specs and this file's Key Rules — understand the current state and constraints
2. **Write a plan to disk** — use the appropriate tier from `specs/framework/TEMPLATES.md`:
- **Large features / new workstreams:** Create a full implementation spec (`specs/projects/sdk/workstreams/<scope>/SPEC.md`)
- **Medium features / multi-chunk work:** Create a session plan file in the project folder or update the relevant SPEC.md
- **Small features / single-chunk fixes:** Add a chunk to an existing SPEC.md, or create a minimal plan in the spec folder
3. **Include in every plan:** scope of work, files modified, I/O examples, validation command, definition of done
4. **Then implement** — update chunk status as you complete work
5. **After completion:** Mark chunks done in both SPEC.md and OVERVIEW.md status checklists
5. **After completion:** Mark chunks done in SPEC.md status tables. Review status checklists at session start — if something is marked "Done" that isn't, or "Pending" that's in progress, fix it first.
Quick-start prompts for creating new specs are in [SPEC-GUIDE.md](./specs/SPEC-GUIDE.md#quick-start).
### Spec-Writing Guidelines
When writing specs, follow these principles so they work as AI agent prompts:
- **Use second person.** "You are making X portable" not "X should be made portable."
- **Be explicit about constraints.** "You will NOT modify..." not just "Focus on..."
- **Provide exact file paths with line numbers.** `src/proving/provingMachine.ts:543` not "the proving machine file."
- **State the validation command.** Agents will run it. If it's not there, they'll skip validation.
- **One chunk = one self-contained prompt.** The chunk must include enough context to execute without reading the full spec.
- **Use `--remote` for M and L chunks.** Medium and large chunks benefit from `claude --remote` so work continues in the background.
### Why Even Minor Features

4
app/AGENTS.md
View File

@@ -258,5 +258,5 @@ See `.cursor/rules/test-memory-optimization.mdc` for comprehensive guidelines, e
The Self Wallet app serves as a **test environment** for the SDK refactor. For SDK architecture context:
- **[SDK Specs](../specs/README.md)** — Table of contents and reading order
- **[SDK Overview](../specs/SDK-OVERVIEW.md)** — System architecture, bridge protocol, decision matrix
- **[SDK Overview](../specs/projects/sdk/OVERVIEW.md)** — System architecture, bridge protocol, decision matrix
- **[SDK Project Index](../specs/projects/sdk/INDEX.md)** — Workstream links and entry point

3
packages/kmp-sdk/shared/src/androidMain/kotlin/xyz/self/sdk/api/SelfSdk.android.kt
View File

@@ -185,6 +185,9 @@ actual class SelfSdk private constructor(
if (boundActivity?.get() === activity) {
boundActivity = null
}
if (Companion.currentActivity?.get() === activity) {
Companion.currentActivity = null
}
pendingCallback?.onCancelled()
pendingCallback = null
lifecycleObserver = null

7
packages/mobile-sdk-alpha/AGENTS.md
View File

@@ -146,11 +146,10 @@ yarn build # Confirm build still works
For architecture context, implementation details, and workstream coordination:
- **[SDK Overview](../../specs/SDK-OVERVIEW.md)** — System architecture, bridge protocol, decision matrix
- **[Person 4 (SDK Core) Spec](../../specs/person4-sdk-core/SPEC.md)** — Implementation chunks for this package (mobile-sdk-alpha)
- **[Person 4 Overview](../../specs/person4-sdk-core/OVERVIEW.md)** — What this workstream owns, dependencies, status
- **[SDK Overview](../../specs/projects/sdk/OVERVIEW.md)** — System architecture, bridge protocol, decision matrix
- **[SDK Core Spec](../../specs/projects/sdk/workstreams/sdk-core/SPEC.md)** — Implementation chunks for this package (mobile-sdk-alpha)
Before implementing SDK work, read `specs/PROJECT-RULES.md` and `specs/person4-sdk-core/SPEC.md` for constraints and validation commands.
Before implementing SDK work, read `CLAUDE.md` Key Rules and `specs/projects/sdk/workstreams/sdk-core/SPEC.md` for constraints and validation commands.
## Notes

2
scripts/kmp-start.sh
View File

@@ -19,7 +19,7 @@ if command -v adb >/dev/null 2>&1; then
done <<< "${device_serials}"
echo "Use http://127.0.0.1:${PORT} on Android devices with adb reverse."
else
echo "No adb devices detected. If using emulator, use http://10.0.2.2:${PORT}."
echo "No adb devices detected. Run 'adb reverse tcp:${PORT} tcp:${PORT}' once a device is connected."
fi
else
echo "adb not found. Skipping reverse setup."

7
specs/ARCHIVE.md
View File

@@ -2,7 +2,8 @@
Append-only log of retired specs. When a spec is fully done and no longer needed for active reference, add a row here.
For full retirement process, see [SPECS-REORG-PLAN.md](./SPECS-REORG-PLAN.md) placement rule 6.
For full retirement process, see [SPECS-REORG-PLAN.md](./archive/SPECS-REORG-PLAN.md) placement rule 6.
| Spec | Retired | Outcome | Key decisions / lessons | Final PR(s) |
| ---- | ------- | ------- | ----------------------- | ----------- |
| Spec | Retired | Outcome | Key decisions / lessons | Final PR(s) |
| --------------------------- | ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------- |
| `specs/SPECS-REORG-PLAN.md` | 2026-03-05 | Reorganization completed and stabilized | Project-first structure adopted; singleton status folder removed; project-level naming standardized | N/A |

71
specs/HANDOFF.md
View File

@@ -1,71 +0,0 @@
# SDK Implementation — Follow-Up Tracker
> Branch: `justin/kmp-wrap-up-evi-handoff-work`
> Last updated: 2026-02-23
> Prior review: 2026-02-19 (`feat/person1-2-3-implementation`)
## What Was Delivered
Five new packages, all implemented. Validation status:
| Package | Tests | Status |
| ----------------------------- | -------------------- | ------ |
| `@selfxyz/webview-bridge` | 63/63 | Done |
| `@selfxyz/webview-app` | — (build-verified) | Done |
| `@selfxyz/rn-sdk` | 64/64 | Done |
| `@selfxyz/self-sdk-swift` | — (compile-verified) | Done |
| `@selfxyz/kmp-minipay-sample` | — (scaffold) | Done |
KMP SDK: `compileKotlinIosSimulatorArm64` + `jvmTest` passing. iOS Maestro launch: 1 test, 0 failures.
Chunk completion: 23/30 done, 3 partial, 1 skipped, 2 superseded, 1 deferred. See [WAVE-PLAN.md](./WAVE-PLAN.md) for details.
## Open Follow-Up Items
### P1 — Validation Gaps
| Item | Owner | Context |
| ----------------------------------------- | -------- | ------------------------------------------------------------ |
| KMP test app validation on both platforms | Person 2 | Compile-verified only; no runtime validation captured. |
| Integration validation in Self Wallet app | Person 5 | `SelfVerification` component not yet wired into Self Wallet. |
### P2 — Correctness / Consistency
| Item | Owner | Context |
| ---------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Consolidate duplicated fallback adapters | Person 4 | ~150 LOC duplicated across `webview-bridge/adapters/` and `mobile-sdk-alpha/adapters/browser/` (analytics, documents, haptic). `mobile-sdk-alpha` is canonical owner; bridge copies are transitional. |
| Source dynamic proving request values from request context | Person 1 | `ProvingScreen` now accepts params but default values are still hardcoded. Config should flow from `SelfSdk.launch(request)`. |
| Expose `generateKey()`/`getPublicKey()` in `BridgeCryptoAdapter` | Person 1/4 | Methods exist in iOS native handler (`CryptoBridgeHandler.kt`) and bridge protocol types (`CryptoMethod`), but the `BridgeCryptoAdapter` interface in `webview-bridge/adapters/crypto.ts` only exposes `hash()` and `sign()`. WebView client code cannot call key management methods. |
### P3 — Publishing / Packaging
| Item | Owner | Context |
| ---------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| npm publish `@selfxyz/rn-sdk` | Person 5 | Package is implemented but not published. |
| Production artifact builds (AAR + XCFramework) | Person 2 | KMP SDK packaging for distribution not finalized. |
| Self Wallet migration to `SelfVerification` | Person 5 | Phase 2 — Self Wallet replaces native verification screens with SDK WebView flow. |
### Deferred (Phase 2)
| Item | Chunk | Context |
| ---------------------------- | ----- | ---------------------------------------------------------------------------------------------------- |
| iOS Camera MRZ Handler (KMP) | 2L | Camera/MRZ on iOS via KMP deferred to Phase 2. RN SDK has its own implementation via native modules. |
## Resolved Decisions (Reference)
These decisions were made during this PR cycle. They are now documented in [SDK-OVERVIEW.md](./SDK-OVERVIEW.md) and do not need further action:
- **Hybrid crypto contract:** `hash()` in WebView, `sign()`/`generateKey()`/`getPublicKey()` native.
- **Fallback adapter ownership:** `mobile-sdk-alpha` is canonical; `webview-bridge` copies are transitional.
- **Platform asymmetry:** Android = 5-handler normative minimum, iOS = 9-handler compatibility superset. Signed off.
- **iOS lifecycle fixes:** Flat payload handling, Mutex synchronization, debug port 5173 — all implemented.
## Suggested Follow-Up PR Order
1. **Correctness cleanup** — Adapter consolidation, dynamic proving config, crypto adapter interface gap
2. **Publishing** — npm publish rn-sdk, finalize AAR/XCFramework packaging
3. **Self Wallet migration** — Wire `SelfVerification` into the main app (Phase 2)
## Architecture Notes
- Draft consolidation plan: [EUCLID-WEB-CONSOLIDATION.md](./EUCLID-WEB-CONSOLIDATION.md)

14
specs/KMP-STATUS.md
View File

@@ -1,14 +0,0 @@
# SDK Status (At a Glance)
> Last updated: 2026-03-02
| Area | Spec | % Done |
| ------------------------------- | ---------------------------- | ------: |
| WebView UI + Bridge | `person1-webview` | 88% |
| KMP Native Shells | `person2-native-shells` | 82% |
| MiniPay Integration Sample | `person3-integrations` | 70% |
| SDK Core (non-web follow-ups) | `person4-sdk-core` | 100% |
| RN Native Shell | `person5-rn-sdk` | 100% |
| Physical Device Validation | cross-spec | 25% |
| Packaging + Publishing | cross-spec | 35% |
| **Overall Program (KMP + Web)** | `SDK-OVERVIEW` + `WAVE-PLAN` | **74%** |

69
specs/README.md
View File

@@ -1,64 +1,39 @@
# Specs
> Project-first table of contents for all specs. Start here.
> Table of contents for all specs. Start here.
## How Specs Are Organized
Specs are organized by **project** first (`kmp`, `sdk`, `lottie`, `euclid`), not by document intent.
- `specs/projects/` — active project specs you implement against
- `specs/topics/` — standalone docs (not full projects)
- `specs/framework/` — templates for writing new specs
- `specs/archive/` — retired specs
- Use `specs/projects/<project>/` for project-owned docs.
- Use `specs/framework/` for generic spec-writing rules/templates.
- Use `specs/shared/` for cross-project handoffs.
## Projects
## Top-Level Navigation
- **[SDK](./projects/sdk/INDEX.md)** — architecture, bridge protocol, workstreams, execution status
- `framework/`
- `SPEC-GUIDE.md`
- `TEMPLATES.md`
- `PROJECT-RULES.md`
- `PRODUCT-SPEC-ENHANCEMENT-PROMPT.md`
## Topics
- `projects/sdk/`
- SDK-wide architecture, wave plan, handoff, and workstreams
- [CI Coverage Gaps](./topics/CI-COVERAGE-GAPS.md)
- [Euclid Web Consolidation](./topics/EUCLID-WEB-CONSOLIDATION.md)
- [Lottie dotLottie Review](./topics/LOTTIE-DOTLOTTIE-REVIEW.md)
- [Security Hardening](./topics/SECURITY-HARDENING.md)
- `projects/kmp/`
- KMP initiative, architecture, status, and KMP-specific planning
## Framework
- `projects/lottie/`
- Lottie migration/review specs
- [Templates](./framework/TEMPLATES.md) — copy-paste templates for all three tiers
- [Product Spec Enhancement Prompt](./framework/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md) — Figma cross-reference agent prompt
- `projects/euclid/`
- Euclid consolidation specs
Project rules and spec-writing guidelines are consolidated in the root `CLAUDE.md`.
- `shared/handoffs/`
- Cross-project security and transition docs
## Other
## Current Canonical Entry Points
- SDK: `specs/projects/sdk/INDEX.md` (planned)
- KMP: `specs/projects/kmp/KMP-SPECS-INDEX.md`
- Folder migration: `specs/SPECS-REORG-PLAN.md`
## Migration Map (Legacy -> Target)
- `specs/SDK-OVERVIEW.md` -> `specs/projects/sdk/SDK-OVERVIEW.md`
- `specs/WAVE-PLAN.md` -> `specs/projects/sdk/WAVE-PLAN.md`
- `specs/HANDOFF.md` -> `specs/projects/sdk/HANDOFF.md`
- `specs/person1-webview/*` -> `specs/projects/sdk/workstreams/webview/*`
- `specs/person2-native-shells/*` -> `specs/projects/sdk/workstreams/native-shells/*`
- `specs/person3-integrations/*` -> `specs/projects/sdk/workstreams/integrations/*`
- `specs/person4-sdk-core/*` -> `specs/projects/sdk/workstreams/sdk-core/*`
- `specs/person5-rn-sdk/*` -> `specs/projects/sdk/workstreams/rn-sdk/*`
- `specs/KMP-STATUS.md` -> `specs/projects/kmp/status/KMP-STATUS.md`
- `specs/lottie-dotlottie-migration/REVIEW.md` -> `specs/projects/lottie/REVIEW.md`
- `specs/EUCLID-WEB-CONSOLIDATION.md` -> `specs/projects/euclid/EUCLID-WEB-CONSOLIDATION.md`
- `specs/handoff-p1-fixes/*` -> `specs/shared/handoffs/p1-fixes/*`
- [Spec Archive](./ARCHIVE.md) — append-only log of retired specs
## Reading Order
1. `specs/README.md`
2. Your project index under `specs/projects/<project>/`
3. Relevant framework docs in `specs/framework/`
4. Project workstream specs
1. This file (`specs/README.md`)
2. `specs/projects/sdk/INDEX.md` — find your workstream
3. The workstream `SPEC.md` — find your chunk
4. `specs/projects/sdk/OVERVIEW.md` — if you need architecture context

142
specs/WAVE-PLAN.md
View File

@@ -1,142 +0,0 @@
# Execution Wave Plan
> Last updated: 2026-02-23
> Project: [SDK-OVERVIEW.md](./SDK-OVERVIEW.md)
Cross-workstream chunk execution plan for parallel AI agent work via `claude --remote`.
## What is a Wave?
A **wave** is a batch of chunks that can execute in parallel because they have no inter-dependencies. Waves are sequenced: Wave 2 starts after Wave 1 completes, because Wave 2 chunks depend on Wave 1 outputs. Within a wave, each chunk runs on a separate AI agent (or developer) simultaneously. This maximizes throughput — instead of executing 27 chunks sequentially, we run them in 5 waves with up to 5 parallel agents per wave.
**Wave != sprint.** Sprints are time-boxed. Waves are dependency-ordered. A wave is done when all its chunks pass validation, regardless of calendar time.
## Chunk Inventory
| Chunk | Workstream | Description | Size | Status | Dependencies |
| ------ | ---------------------------- | ---------------------------------------------- | ----- | ------------------- | ------------ |
| 4A | Person 4 (SDK Core) | Config & Platform Abstraction | S | Done | — |
| 4B | Person 4 (SDK Core) | Browser Entry Point & Package Exports | S | Done | 4A |
| 4C | Person 4 (SDK Core) | WebView Lifecycle Events | S | Done | 4B |
| 4D | Person 4 (SDK Core) | WsAdapter Integration (optional) | M | Skipped | 4C |
| 4E | Person 4 (SDK Core) | Conditional SelfApp Store | S | Done | 4A |
| **4F** | **Person 4 (SDK Core)** | **Web Fallback Adapter Implementations** | **M** | **Done** | 4B |
| 1F | Person 1 (WebView) | Bridge Package | L | Done | — |
| 1B | Person 1 (WebView) | Onboarding Screens (5) | M | Done | 1F |
| 1C | Person 1 (WebView) | Proving + Result Screens | M | Done | 1F |
| 1D | Person 1 (WebView) | Remaining Screens (Home, Settings, ComingSoon) | S | Done | 1F |
| **1E** | **Person 1 (WebView)** | **WebView App Shell (Vite + router)** | **M** | **Partial** | 1D |
| 2A | Person 2 (Native Shells) | KMP Setup + Bridge Protocol | S | Done | — |
| 2B | Person 2 (Native Shells) | Android WebView Host | S | Done | 2A |
| 2C | Person 2 (Native Shells) | Android Native Handlers (5) | L | Done | 2B |
| 2D | Person 2 (Native Shells) | iOS WebView Host + Provider Infra (stub) | M | Superseded by 2G-2K | — |
| 2E | Person 2 (Native Shells) | iOS Native Handlers (stub) | M | Superseded by 2G-2K | 2D |
| 2F | Person 2 (Native Shells) | SDK Public API finalize | M | Partial | 2C, 2K |
| **2G** | **Person 2 (Native Shells)** | **iOS Factory Infrastructure** | **S** | **Done** | — |
| **2H** | **Person 2 (Native Shells)** | **iOS Biometric Handler** | **S** | **Done** | 2G |
| **2I** | **Person 2 (Native Shells)** | **iOS Lifecycle Handler** | **S** | **Done** | 2G |
| **2J** | **Person 2 (Native Shells)** | **iOS WebView + launch()** | **M** | **Done** | 2G, 2H, 2I |
| **2K** | **Person 2 (Native Shells)** | **iOS NFC Handler** | **M** | **Done** | 2J |
| **5A** | **Person 5 (RN SDK)** | **Package + Component + Router** | **M** | **Done** | — |
| **5B** | **Person 5 (RN SDK)** | **Biometric + Keychain Handlers** | **S** | **Done** | 5A |
| **5C** | **Person 5 (RN SDK)** | **NFC + Camera Handlers** | **L** | **Done** | 5A |
| **5D** | **Person 5 (RN SDK)** | **Asset Bundling** | **M** | **Done** | 5A-5C, 1E |
| **3A** | **Person 3 (Integrations)** | **MiniPay Project Setup** | **M** | **Done** | — |
| **3B** | **Person 3 (Integrations)** | **Wire SelfSdk.launch()** | **M** | **Done** | 3A |
| **3C** | **Person 3 (Integrations)** | **Polish + Error Handling** | **S** | **Partial** | 3B |
| 2L | Person 2 (Native Shells) | Camera MRZ Handler (iOS) | S | Deferred (Phase 2) | 2J |
**Totals (reconciled 2026-02-23):** 30 chunks — 23 done, 3 partial (1E, 2F, 3C), 1 skipped (4D optional), 2 superseded (2D/2E → 2G-2K), 1 deferred (2L Phase 2).
**Remaining to close:** 4 items (3 partial + 1 deferred).
## Reconciliation Notes (2026-02-23)
- This file now reflects post-implementation reconciliation, not just pre-execution planning.
- The older aggregate summary (`11 done / 13 pending`) was stale and has been replaced by audited counts.
- Decision/documentation blockers from the 2026-02-19 handoff are now reconciled:
- hybrid crypto + fallback ownership decisions are explicit
- iOS/Android asymmetry contract is documented and signed off
- Remaining partials are now primarily residual implementation cleanup (fallback adapter de-duplication + dynamic proving request config).
- Key carry-forward risks are tracked in `specs/HANDOFF.md`.
## Execution Waves
### Wave 1 — 4 parallel agents
No cross-dependencies. All can start immediately.
| Agent | Chunk | Workstream | Size | Notes |
| ----- | ----- | --------------------------------------- | ----- | -------------------------- |
| A | 4F | Person 4 — Web Fallback Adapters | M ~6k | Last SDK core chunk |
| B | 1E | Person 1 — WebView App Shell | M ~8k | In progress, Vite + router |
| C | 2G | Person 2 — iOS Factory Infrastructure | S ~3k | Starts iOS chain |
| D | 5A | Person 5 — Package + Component + Router | M ~8k | Starts RN SDK chain |
### Wave 2 — 5 parallel agents
Starts after Wave 1 completes. Each chunk's predecessor is listed.
| Agent | Chunk | Workstream | Size | Predecessor |
| ----- | ----- | -------------------------------- | ------ | ----------------------------- |
| A | 2H | Person 2 — iOS Biometric Handler | S ~2k | 2G |
| B | 2I | Person 2 — iOS Lifecycle Handler | S ~2k | 2G |
| C | 5B | Person 5 — Biometric + Keychain | S ~4k | 5A |
| D | 5C | Person 5 — NFC + Camera Handlers | L ~10k | 5A |
| E | 3A | Person 3 — MiniPay Project Setup | M ~6k | None (soft block on Person 2) |
### Wave 3 — 3 parallel agents
| Agent | Chunk | Workstream | Size | Predecessor |
| ----- | ----- | --------------------------------- | ----- | ----------- |
| A | 2J | Person 2 — iOS WebView + launch() | M ~5k | 2G, 2H, 2I |
| B | 3B | Person 3 — Wire SelfSdk.launch() | M ~5k | 3A |
| C | 5D | Person 5 — Asset Bundling | M ~6k | 5A-5C, 1E |
### Wave 4 — 2 parallel agents
| Agent | Chunk | Workstream | Size | Predecessor |
| ----- | ----- | ---------------------------------- | ----- | ----------- |
| A | 2K | Person 2 — iOS NFC Handler | M ~5k | 2J |
| B | 3C | Person 3 — Polish + Error Handling | S ~4k | 3B |
### Wave 5 — 1 agent
| Agent | Chunk | Workstream | Size | Predecessor |
| ----- | ----- | ---------------------------------- | ----- | ----------- |
| A | 2F | Person 2 — SDK Public API finalize | M ~5k | 2C, 2K |
## Dependency Graph
```
Wave 1 (parallel): 4F 1E 2G 5A
│ │ │ ├──────┐
Wave 2 (parallel): │ │ 2H 2I 5B 5C 3A
│ │ │ │ │ │ │
Wave 3 (parallel): │ │ 2J 5D←──1E 3B
│ │ │ │
Wave 4 (parallel): │ │ 2K 3C
│ │ │
Wave 5: ▼ ▼ 2F
DONE DONE │
▼
DONE
```
## Critical Path
The longest dependency chain determines minimum wall-clock time:
```
2G → 2H/2I → 2J → 2K → 2F
S S/S M M M
```
This iOS chain spans Waves 1–5 (5 sequential steps). Everything else can parallelize around it. **Person 2's iOS work is the bottleneck.** If iOS slips, the SDK public API (2F) slips.
## Notes
- **2D/2E overlap**: Chunks 2D and 2E were the original iOS stubs. They are superseded by the 2G→2K Swift wrapper chain. The wave plan uses 2G-2K.
- **2L deferred**: Camera MRZ on iOS (Chunk 2L) is Phase 2. Not scheduled in any wave. Add to a future wave when Phase 2 planning starts.
- **3A soft block**: MiniPay sample technically depends on Person 2's KMP SDK artifact, but project scaffolding (3A) can proceed with mocks. Hard dependency starts at 3B.
- **5D depends on 1E**: Asset bundling needs the Vite bundle output from Person 1's WebView app shell.
- **Use `claude --remote`** for M and L chunks to avoid tying up terminals.

6
specs/PROJECT-RULES.md → specs/archive/PROJECT-RULES.md
View File

@@ -2,7 +2,7 @@
> Rules specific to the Self SDK project. Global rules apply to everyone.
> Section rules apply to that workstream. Each rule has a one-line rationale.
> Read with [SDK-OVERVIEW.md](./SDK-OVERVIEW.md) when it exists.
> Read with [SDK Overview](../projects/sdk/OVERVIEW.md) when it exists.
## Global Rules
@@ -52,7 +52,7 @@
- UI components shared between flows → `mobile-sdk-alpha`
- Only screen-level composition and routing belong in `webview-app`
18. **New native handlers MUST follow the bridge protocol exactly.** Every native handler implements the JSON schema defined in SDK-OVERVIEW.md (request/response/event). No custom messaging, no side channels, no platform-specific extensions. The WebView must not know which native shell it's running inside.
18. **New native handlers MUST follow the bridge protocol exactly.** Every native handler implements the JSON schema defined in OVERVIEW.md (request/response/event). No custom messaging, no side channels, no platform-specific extensions. The WebView must not know which native shell it's running inside.
### Code
@@ -78,7 +78,7 @@
### Planning
28. **Write plans to disk before executing.** When working on multi-step tasks (multiple chunks, cross-workstream coordination, or anything requiring more than one session), write the plan to a file BEFORE starting implementation. Update WAVE-PLAN.md, the relevant SPEC.md status table, or create a session-specific plan file. A plan that only exists in session memory will be lost to API errors, context overflow, or `/clear`. Writing it to disk enables multiple agents to work from the same plan and creates an audit trail.
28. **Write plans to disk before executing.** When working on multi-step tasks (multiple chunks, cross-workstream coordination, or anything requiring more than one session), write the plan to a file BEFORE starting implementation. Update the project PLAN.md, the relevant SPEC.md status table, or create a session-specific plan file. A plan that only exists in session memory will be lost to API errors, context overflow, or `/clear`. Writing it to disk enables multiple agents to work from the same plan and creates an audit trail.
29. **Update plan files as you go.** When a chunk is completed, mark it done in the plan file immediately. When scope changes, update the plan file. The plan file is the single source of truth for what's been done and what's next — not the session transcript.

90
specs/SPEC-GUIDE.md → specs/archive/SPEC-GUIDE.md
View File

@@ -9,7 +9,7 @@ Copy-paste one of these prompts to start a new spec session:
**New project overview (tier 1 — architecture):**
```text
Read specs/SPEC-GUIDE.md, specs/PROJECT-RULES.md, and specs/TEMPLATES.md (Project Overview section).
Read specs/framework/SPEC-GUIDE.md, specs/framework/PROJECT-RULES.md, and specs/framework/TEMPLATES.md (Project Overview section).
Then analyze the codebase to create a project overview for [PROJECT NAME].
Before writing, research:
@@ -18,7 +18,7 @@ Before writing, research:
- Dependencies between components
- What's done vs what's remaining
Write the spec to specs/SDK-OVERVIEW.md using the template.
Write the spec to specs/projects/[project]/OVERVIEW.md using the template.
Do not skip: north star, architecture diagram, module table, status checklist, system-level I/O.
Run the review checklist from SPEC-GUIDE.md before finishing.
```
@@ -26,8 +26,8 @@ Run the review checklist from SPEC-GUIDE.md before finishing.
**New workstream overview (tier 2 — orientation for a specific workstream):**
```text
Read specs/SPEC-GUIDE.md, specs/PROJECT-RULES.md, specs/TEMPLATES.md (Workstream Overview section),
and specs/SDK-OVERVIEW.md.
Read specs/framework/SPEC-GUIDE.md, specs/framework/PROJECT-RULES.md, specs/framework/TEMPLATES.md (Workstream Overview section),
and specs/projects/sdk/OVERVIEW.md.
Then analyze the codebase to create a workstream overview for [PERSON/SCOPE].
Before writing, research:
@@ -36,7 +36,7 @@ Before writing, research:
- Current status and milestones
- Key decisions specific to this workstream
Write the spec to specs/[person-scope]/OVERVIEW.md using the template.
Write the spec to specs/projects/[project]/workstreams/[scope]/OVERVIEW.md using the template.
Do not skip: north star, what you own, architecture context diagram, dependencies table,
status milestones, deliverables.
Run the review checklist from SPEC-GUIDE.md before finishing.
@@ -45,9 +45,9 @@ Run the review checklist from SPEC-GUIDE.md before finishing.
**New implementation spec (tier 3 — for a specific workstream):**
```text
Read specs/SPEC-GUIDE.md, specs/PROJECT-RULES.md, specs/TEMPLATES.md (Implementation Spec section),
and specs/[person-scope]/OVERVIEW.md.
Then analyze the codebase to create an implementation spec for [PERSON/SCOPE].
Read specs/framework/SPEC-GUIDE.md, specs/framework/PROJECT-RULES.md, specs/framework/TEMPLATES.md (Implementation Spec section),
and specs/projects/[project]/workstreams/[scope]/OVERVIEW.md.
Then analyze the codebase to create an implementation spec for [SCOPE].
Before writing, research:
- The specific files this workstream will touch (read them, check line numbers)
@@ -55,7 +55,7 @@ Before writing, research:
- Dependencies on other workstreams
- What's already been implemented vs what remains
Write the spec to specs/[person-scope]/SPEC.md using the template.
Write the spec to specs/projects/[project]/workstreams/[scope]/SPEC.md using the template.
Do not skip: problem table with file:line refs, I/O examples per task and chunk,
files in/out of scope, token-budgeted chunks, definition of done.
Run the review checklist from SPEC-GUIDE.md before finishing.
@@ -64,7 +64,7 @@ Run the review checklist from SPEC-GUIDE.md before finishing.
**Refactor an existing spec to match the new format:**
```text
Read specs/SPEC-GUIDE.md, specs/PROJECT-RULES.md, and specs/TEMPLATES.md.
Read specs/framework/SPEC-GUIDE.md, specs/framework/PROJECT-RULES.md, and specs/framework/TEMPLATES.md.
Then read the existing spec at specs/[OLD-SPEC].md.
Refactor it to match the template format. Analyze the codebase to verify:
@@ -91,11 +91,11 @@ A good spec lets a new dev comprehend the system in 60 seconds and lets an AI ag
Every project has three types of specs:
| Tier | File | Audience | Purpose | Change Frequency |
| ----------------------- | ---------------------- | ---------------------------- | -------------------------------------------------------- | ---------------- |
| **Project Overview** | `SDK-OVERVIEW.md` | Architect, eng lead, new dev | System-level architecture, ties all workstreams together | Rarely |
| **Workstream Overview** | `person-*/OVERVIEW.md` | Dev joining a workstream | What this workstream owns, dependencies, status, context | Occasionally |
| **Implementation** | `person-*/SPEC.md` | Implementer (human or agent) | Exact scope, code changes, I/O, token-budgeted chunks | Frequently |
| Tier | File | Audience | Purpose | Change Frequency |
| ----------------------- | --------------------------------- | ---------------------------- | -------------------------------------------------------- | ---------------- |
| **Project Overview** | `OVERVIEW.md` | Architect, eng lead, new dev | System-level architecture, ties all workstreams together | Rarely |
| **Workstream Overview** | `workstreams/<scope>/OVERVIEW.md` | Dev joining a workstream | What this workstream owns, dependencies, status, context | Occasionally |
| **Implementation** | `workstreams/<scope>/SPEC.md` | Implementer (human or agent) | Exact scope, code changes, I/O, token-budgeted chunks | Frequently |
The project overview is the map. The workstream overview is orientation for a new team member. The implementation spec is turn-by-turn directions. All three reference each other.
@@ -105,7 +105,7 @@ All three templates live in `TEMPLATES.md` — pick the section that matches wha
Templates are useless without a research process. Follow this workflow:
1. **Read** `SDK-OVERVIEW.md` and `PROJECT-RULES.md` — understand the system and constraints
1. **Read** the project `OVERVIEW.md` and `PROJECT-RULES.md` — understand the system and constraints
2. **Analyze the codebase** — run the code, read key files, check test coverage, review open PRs. Don't assume — verify.
3. **Fill in the Problem section first** — this forces you to do real research before writing solutions
4. **Write scope of work with I/O examples** — if you can't write the I/O, you don't understand the requirement
@@ -114,7 +114,7 @@ Templates are useless without a research process. Follow this workflow:
## Rules Reminder
Every spec must respect [PROJECT-RULES.md](./PROJECT-RULES.md). When writing chunk instructions, apply the rules that are relevant to the work — especially the **Reuse & Maintainability** section for UI/component work and the **Architecture** section for native/bridge work. Don’t cargo-cult UI rules into non-UI specs or vice versa.
Every spec must respect [Project Rules](./PROJECT-RULES.md). When writing chunk instructions, apply the rules that are relevant to the work — especially the **Reuse & Maintainability** section for UI/component work and the **Architecture** section for native/bridge work. Don’t cargo-cult UI rules into non-UI specs or vice versa.
Also:
@@ -148,7 +148,7 @@ Specs serve as prompts. Write them so an AI agent can produce a correct PR from
- **One chunk = one self-contained prompt.** The chunk must include enough context to execute without reading the full spec. Reference specific sections of the spec if needed, but don't assume the agent has read everything.
- **Distinguish modification from creation.** Use BEFORE/AFTER for existing files. Use "Create" + skeleton + interface it implements for new files.
- **Use `--remote` for M and L chunks.** Medium and large chunks benefit from running Claude Code with `claude --remote` so work continues in the background without tying up a terminal. This is especially useful when running multiple chunks in parallel across different workstreams.
- **Write plans to disk before executing.** Before starting multi-step work, write the plan to a file (update WAVE-PLAN.md, SPEC.md status tables, or create a session plan file). Session memory is ephemeral — API errors, context overflow, or `/clear` will destroy it. A plan on disk survives session loss, enables multiple agents to work from the same plan, and creates an audit trail. Never rely on session transcript as the only record of what was planned.
- **Write plans to disk before executing.** Before starting multi-step work, write the plan to a file (update the project PLAN.md, SPEC.md status tables, or create a session plan file). Session memory is ephemeral — API errors, context overflow, or `/clear` will destroy it. A plan on disk survives session loss, enables multiple agents to work from the same plan, and creates an audit trail. Never rely on session transcript as the only record of what was planned.
## Strong Suggestions
@@ -290,30 +290,46 @@ This keeps accountability without rigidity. Development has no hard and fast rul
```text
specs/
SPEC-GUIDE.md <- This file (generic, portable)
PROJECT-RULES.md <- Project-specific rules
TEMPLATES.md <- All three templates in one file
SDK-OVERVIEW.md <- The project architecture spec (stable)
README.md <- Table of contents (start here)
ARCHIVE.md <- Append-only log of retired specs
person1-webview/
OVERVIEW.md <- Person 1's workstream overview (stable)
SPEC.md <- Person 1's implementation spec (living)
framework/
SPEC-GUIDE.md <- This file (generic, portable)
PROJECT-RULES.md <- Project-specific rules
TEMPLATES.md <- All three templates in one file
person2-native-shells/
OVERVIEW.md <- Person 2's workstream overview (stable)
SPEC.md <- Person 2's implementation spec (living)
projects/
sdk/
INDEX.md <- SDK project entrypoint
OVERVIEW.md <- Architecture spec (stable)
PLAN.md <- Execution wave plan
HANDOFF.md <- Follow-up tracker
STATUS.md <- SDK-wide status
workstreams/
webview/ <- WebView UI + bridge
native-shells/ <- KMP native shells
integrations/ <- MiniPay + samples
sdk-core/ <- SDK core adaptation
rn-sdk/ <- React Native SDK
personN-scope/
OVERVIEW.md <- Workstream overview
SPEC.md <- Implementation spec
kmp/
INDEX.md <- KMP entrypoint
ARCHITECTURE.md
INITIATIVE.md
REORG-PLAN.md
personN-integrations/
OVERVIEW.md <- Integration workstream overview
SPEC-[NAME].md <- Integration-specific implementation specs
lottie/ <- Lottie migration
euclid/ <- Euclid consolidation
ci/ <- CI coverage specs
shared/
handoffs/ <- Cross-project handoffs
archive/ <- Archived/retired spec plans
```
Each person gets a folder with two files: `OVERVIEW.md` (what you own, context, dependencies — changes rarely) and `SPEC.md` (how to build it, chunks, code — changes often). Integration specs that span multiple workstreams live in `integrations/`.
Each workstream gets a folder with two files: `OVERVIEW.md` (what you own, context, dependencies — changes rarely) and `SPEC.md` (how to build it, chunks, code — changes often). Integration specs that span multiple workstreams live in `integrations/`.
## Gold Standard Reference
## Reference Implementation
When filling in a template, use `person4-sdk-core/SPEC.md` as the reference implementation of a well-executed implementation spec. It demonstrates: concrete file:line problem identification, BEFORE/AFTER code blocks, decision points with recommendations, files in/out of scope, token-sized chunks with dependency graphs, and multi-level validation plans.
Use `projects/sdk/workstreams/sdk-core/SPEC.md` as the reference when filling in a template. It demonstrates: concrete file:line problem identification, BEFORE/AFTER code blocks, decision points with recommendations, files in/out of scope, token-sized chunks with dependency graphs, and multi-level validation plans.

164
specs/archive/SPECS-REORG-PLAN.md Normal file
View File

@@ -0,0 +1,164 @@
# Specs Folder Reorganization Plan (Project-First)
Last updated: March 5, 2026
Owner: SDK/specs maintainers
Status: Complete
## Decision
Use a **project-first** structure for `specs/`.
Why:
- Work typically starts from project context (`kmp`, `lottie`, `sdk`, `euclid`).
- Agents can resolve scope faster with one project root.
- Cross-project docs are the minority and can live in shared buckets.
## Goals
- Make each project's docs discoverable under one folder.
- Keep generic authoring rules separate from project specs.
- Reduce mixed flat files and stale links.
- Preserve compatibility during migration with path mapping.
## Target Structure
```text
specs/
README.md
SPECS-REORG-PLAN.md
framework/
SPEC-GUIDE.md
TEMPLATES.md
PROJECT-RULES.md
PRODUCT-SPEC-ENHANCEMENT-PROMPT.md
projects/
sdk/
INDEX.md
SDK-OVERVIEW.md
WAVE-PLAN.md
HANDOFF.md
status/
SDK-STATUS.md
workstreams/
webview/
native-shells/
integrations/
sdk-core/
rn-sdk/
kmp/
INDEX.md
KMP-ARCHITECTURE.md
KMP-INITIATIVE.md
KMP-REORG-PLAN.md
workstreams/
lottie/
INDEX.md
REVIEW.md
euclid/
INDEX.md
EUCLID-WEB-CONSOLIDATION.md
shared/
handoffs/
p1-fixes/
SECURITY-HARDENING.md
archive/
ARCHIVE.md # append-only table of retired specs
sdk/ # full-text copies of retired SDK specs (optional)
kmp/ # full-text copies of retired KMP specs (optional)
```
## Placement Rules
1. If a spec is mainly about one project, place it under `specs/projects/<project>/`.
2. Only generic spec system docs go in `specs/framework/`.
3. Cross-project coordination and follow-ups go in `specs/shared/`.
4. Every project folder should have an `INDEX.md` as its entrypoint.
5. New implementation specs should include: `Owner`, `Status`, `Last updated`, `Validation commands`.
6. When a spec is fully done: add a row to `specs/ARCHIVE.md` with outcome + key decisions. Either delete the source files (if the "What Was Built" appendix was added per SPEC-GUIDE) or move them to `specs/archive/<project>/`. Workstream OVERVIEW.md files stay until the workstream itself is retired.
## Migration Map (Current -> Target)
Framework:
- `specs/SPEC-GUIDE.md` -> `specs/framework/SPEC-GUIDE.md`
- `specs/TEMPLATES.md` -> `specs/framework/TEMPLATES.md`
- `specs/PROJECT-RULES.md` -> `specs/framework/PROJECT-RULES.md`
- `specs/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md` -> `specs/framework/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md`
SDK project:
- `specs/SDK-OVERVIEW.md` -> `specs/projects/sdk/OVERVIEW.md`
- `specs/WAVE-PLAN.md` -> `specs/projects/sdk/PLAN.md`
- `specs/HANDOFF.md` -> `specs/projects/sdk/HANDOFF.md`
- `specs/person1-webview/*` -> `specs/projects/sdk/workstreams/webview/*`
- `specs/person2-native-shells/*` -> `specs/projects/sdk/workstreams/native-shells/*`
- `specs/person3-integrations/*` -> `specs/projects/sdk/workstreams/integrations/*`
- `specs/person4-sdk-core/*` -> `specs/projects/sdk/workstreams/sdk-core/*`
- `specs/person5-rn-sdk/*` -> `specs/projects/sdk/workstreams/rn-sdk/*`
KMP project:
- `specs/KMP-STATUS.md` -> `specs/projects/sdk/STATUS.md` (relocated as SDK-wide status)
- `specs/projects/kmp/KMP-*.md` -> keep under `specs/projects/kmp/`
Lottie project:
- `specs/lottie-dotlottie-migration/REVIEW.md` -> `specs/projects/lottie/REVIEW.md`
Euclid project:
- `specs/EUCLID-WEB-CONSOLIDATION.md` -> `specs/projects/euclid/PLAN.md`
Shared:
- `specs/handoff-p1-fixes/*` -> `specs/shared/handoffs/p1-fixes/*`
## Rollout Phases
### Phase 1: Index and Policy
- Update `specs/README.md` to project-first navigation.
- Keep a migration mapping table in `README` during transition.
### Phase 2: Create Target Dirs
- Create `framework/`, `projects/*`, `shared/` roots.
- Add `INDEX.md` placeholders for `sdk`, `kmp`, `lottie`, `euclid`.
### Phase 3: Move Project-Level Docs
- Move `SDK-OVERVIEW`, `WAVE-PLAN`, `HANDOFF`, KMP status, lottie review, euclid consolidation.
- Update links in moved docs.
### Phase 4: Move Workstreams
- Move `person*` directories to `projects/sdk/workstreams/*`.
- Update references from old paths.
### Phase 5: Cleanup
- Remove old-path mapping table after link convergence.
- Add optional metadata validation script for required headings.
## Validation Checklist
- `find specs -maxdepth 5 -type f | sort`
- `rg -n "person[1-5]-|SDK-STATUS.md|lottie-dotlottie-migration|EUCLID-WEB-CONSOLIDATION" specs`
- `rg -n "\]\(\./" specs` (relative-link sanity)
## Immediate Next Steps (Historical)
All items below are complete as of 2026-03-05.
1. Create project `INDEX.md` files for `sdk`, `kmp`, `lottie`, `euclid`.
2. Move `KMP-STATUS.md` into `projects/sdk/status/SDK-STATUS.md`.
3. Move `lottie-dotlottie-migration/REVIEW.md` into `projects/lottie/`.
4. Move `EUCLID-WEB-CONSOLIDATION.md` into `projects/euclid/`.

104
specs/archive/kmp/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,104 @@
# KMP Architecture
Last updated: March 5, 2026
Owner: KMP program
Status: Draft
## Purpose
Define the canonical architecture for KMP SDK delivery, runtime behavior, and integration contracts.
## Scope
In scope:
- KMP SDK (`packages/kmp-sdk`)
- KMP SDK test app (`packages/kmp-sdk-test-app` target name)
- Swift companion package (`packages/self-sdk-swift`)
- Bridge contract and handler lifecycle
Out of scope:
- Product requirements and roadmap sequencing (see `INITIATIVE.md`)
- Detailed task breakdowns per implementation chunk
## System Context
- Host apps launch SDK runtime.
- SDK runtime hosts WebView flow and routes bridge messages.
- Native handlers execute platform-specific actions.
- Results are returned through bridge responses to web layer.
## Module Boundaries
1. `kmp-sdk`
- Public API surface (`configure`, `launch`, callbacks)
- Shared bridge models and router
- Android and iOS native handler bindings
2. `self-sdk-swift`
- iOS-native provider implementations
- Factory/config wiring for KMP iOS side
3. `kmp-sdk-test-app`
- Integration harness for Android/iOS manual validation
- Non-production sample host and verification scenarios
## Runtime Flow
1. App initializes SDK config.
2. SDK launches WebView host.
3. Web layer sends bridge request.
4. Router dispatches to native handler.
5. Native result/error marshalled to bridge response.
6. Web flow proceeds or fails with typed error.
## Bridge Contract
Required sections for future expansion:
- Message envelope format
- Request/response typing rules
- Error code taxonomy
- Timeout/retry semantics
- Version compatibility policy
## Platform Notes
### Android
- Activity/webview host lifecycle ownership
- NFC/camera/permission handling responsibilities
- Threading model expectations
### iOS
- Provider delegation into Swift package
- View controller presentation ownership
- Permission and lifecycle edge cases
## Security and Privacy
- Sensitive data handling boundaries
- Logging restrictions (no secrets/PII)
- Storage and retention rules
## Validation Matrix
- Unit: router + handler contracts
- Build: android + ios compile targets
- Integration: test app verification flows
- Device: physical NFC/passport success and failure cases
## Open Decisions
- [ ] Decision 1: _TBD_
- [ ] Decision 2: _TBD_
- [ ] Decision 3: _TBD_
## Change Log
- 2026-03-05: Initial architecture skeleton created.

41
specs/archive/kmp/INDEX.md Normal file
View File

@@ -0,0 +1,41 @@
# KMP Specs Index
Last updated: March 5, 2026
Owner: KMP program
Status: Active
## Start Here
1. [KMP Initiative](./INITIATIVE.md) — goals, scope, milestones.
2. [KMP Architecture](./ARCHITECTURE.md) — technical boundaries and runtime model.
3. [KMP Reorg Plan](./REORG-PLAN.md) — migration phases and execution checklist.
## Canonical Paths
- `specs/projects/kmp/INITIATIVE.md`
- `specs/projects/kmp/ARCHITECTURE.md`
- `specs/projects/kmp/REORG-PLAN.md`
- `specs/projects/sdk/OVERVIEW.md` (SDK-wide execution status — see "Execution Status" section)
- `specs/projects/sdk/workstreams/native-shells/` (active KMP execution stream)
- `specs/projects/sdk/workstreams/integrations/` (cross-SDK integration execution)
## Working Rules for Agents
- Prefer canonical KMP paths over legacy `person*` docs for KMP planning.
- Record `Last updated` date on each material change.
- Include validation commands in implementation-facing specs.
- Mark unresolved items in `Open Decisions` sections.
## Migration Tracking
- [x] Reorg plan created
- [x] Architecture skeleton created
- [x] Initiative skeleton created
- [x] Status moved to `specs/projects/sdk/OVERVIEW.md` "Execution Status" section (relocated — SDK-wide)
- [x] KMP execution location clarified under `specs/projects/sdk/workstreams/*`
- [x] Legacy path mapping added to top-level `specs/README.md`
## Change Log
- 2026-03-05: Initial KMP spec index skeleton created.
- 2026-03-05: Removed stale planned `specs/projects/kmp/workstreams/` target; confirmed active execution remains under `specs/projects/sdk/workstreams/*`.

96
specs/archive/kmp/INITIATIVE.md Normal file
View File

@@ -0,0 +1,96 @@
# KMP Initiative
Last updated: March 5, 2026
Owner: KMP program
Status: Draft
## Problem Statement
KMP specs and DX entrypoints are currently fragmented across mixed naming and locations, increasing onboarding time and execution errors for contributors and agents.
## Goals
- Standardize KMP naming across package folders, commands, and specs.
- Consolidate KMP specs under one project-intent hierarchy.
- Establish architecture and initiative docs as canonical entrypoints.
- Improve agent execution reliability with explicit ownership and validation.
## Non-Goals
- Redesigning non-KMP project spec systems in this initiative.
- Reworking product requirements outside KMP scope.
- Renaming KMP workspace package names.
## Deliverables
1. KMP spec tree under `specs/projects/kmp/`
2. Command taxonomy (`kmp:sdk:*`, `kmp:test-app:*`, `kmp:all:*`)
3. Test app folder rename to `kmp-sdk-test-app` (workspace package name unchanged)
4. Migration map from legacy paths and command aliases
5. Agent hygiene fields enforced in KMP workstream specs
## Milestones
1. Foundation docs
- `INDEX.md`
- `ARCHITECTURE.md`
- `INITIATIVE.md`
2. Command migration
- Add new namespaced commands
- Keep compatibility aliases
3. Naming migration
- Folder rename for test app (`packages/kmp-test-app` -> `packages/kmp-sdk-test-app`)
- Keep `@selfxyz/kmp-test-app` unchanged
- Repo-wide path reference update
4. Spec migration
- Move KMP-relevant docs into new hierarchy
- Add redirects/mapping
5. Cleanup
- Remove deprecated aliases after signoff window
## Owners
- Initiative lead: _TBD_
- DX/commands: _TBD_
- Specs migration: _TBD_
- Validation/CI: _TBD_
## Dependencies
- Agreement on final package folder naming
- Agreement on command namespace policy
- Coordination with ongoing KMP implementation work
## Risks
1. Stale links and references after migration
2. Temporary confusion during alias period
3. Spec drift without ownership/date stamping
## Acceptance Criteria
- New KMP entrypoint exists and is linked from top-level specs index.
- New commands cover all existing KMP workflows.
- Legacy references are either migrated or mapped.
- KMP specs include owner/dependencies/validation metadata.
## Rollout Plan
1. Land docs and command taxonomy.
2. Land package folder rename.
3. Land spec migration and mapping.
4. Remove deprecated aliases after agreed window.
## Change Log
- 2026-03-05: Initial initiative skeleton created.
- 2026-03-05: Updated naming plan to folder rename only; workspace package name unchanged.

190
specs/archive/kmp/REORG-PLAN.md Normal file
View File

@@ -0,0 +1,190 @@
# KMP Specs and DX Reorganization Plan
Last updated: March 5, 2026
Owner: KMP program
Status: Proposed
## Objective
Reorganize KMP specs and developer experience surface areas so contributors and agents can find the right docs quickly, run the right commands consistently, and execute changes with clear ownership boundaries.
## Success Criteria
- KMP specs are grouped by project intent under a dedicated KMP project tree.
- KMP package naming is consistent (`kmp-sdk`, `kmp-sdk-test-app` folder naming).
- Root command surface is explicit, discoverable, and backward-compatible during migration.
- Architecture and initiative docs exist and become the canonical KMP entrypoints.
- Agents can navigate and execute work with minimal ambiguity.
## Naming and Structure Standards
1. Package naming standard
- Keep SDK package as `kmp-sdk`.
- Rename test host app folder from `kmp-test-app` to `kmp-sdk-test-app`.
- Keep workspace package name as `@selfxyz/kmp-test-app` (no package rename).
2. Spec naming standard
- Use `KMP-` prefix for KMP-wide docs.
- Use `KMP-<TRACK>-<TOPIC>.md` for scoped docs (example: `KMP-NATIVE-API.md`).
3. Canonical KMP spec tree
- `specs/projects/kmp/README.md`
- `specs/projects/kmp/ARCHITECTURE.md`
- `specs/projects/kmp/INITIATIVE.md`
- `specs/projects/sdk/OVERVIEW.md` (SDK-wide status — see "Execution Status" section)
- `specs/projects/kmp/workstreams/*`
- `specs/projects/kmp/INDEX.md`
- `specs/projects/kmp/KMP-DECISIONS.md`
- `specs/projects/kmp/KMP-CHANGELOG.md`
## Command Surface Reorganization
Update root `package.json` KMP scripts into explicit namespaces:
1. SDK commands
- `kmp:sdk:build`
- `kmp:sdk:test`
- `kmp:sdk:lint`
- `kmp:sdk:format`
- `kmp:sdk:clean`
2. Test app commands
- `kmp:test-app:android`
- `kmp:test-app:ios`
- `kmp:test-app:build`
- `kmp:test-app:test`
- `kmp:test-app:lint`
- `kmp:test-app:format`
- `kmp:test-app:clean`
3. Orchestration commands
- `kmp:all:check` (lint + test + build)
- `kmp:all:clean`
- `kmp:all:dev`
4. Backward compatibility
- Keep existing `kmp:*` aliases mapped to new commands for 1-2 release cycles.
- Add deprecation notes in script descriptions and docs.
## Required New Docs
1. `ARCHITECTURE.md`
- Module boundaries and ownership
- Runtime flow diagrams (Android/iOS)
- Bridge contract and handler lifecycle
- Integration points with RN SDK/WebView artifacts
- Risk areas and validation matrix
2. `INITIATIVE.md`
- Problem statement
- Goals and non-goals
- Milestones and deliverables
- Owners and decision records
- Rollout and acceptance criteria
## Agent-Focused Spec Hygiene
Add the following to each KMP workstream spec:
- `Owner`
- `Depends On`
- `Inputs`
- `Outputs`
- `Safe-to-edit paths`
- `Do-not-edit paths`
- `Validation commands`
- `Last verified` date
Add a lightweight validator script to enforce required headings in KMP spec files.
## Migration Plan
### Phase 1: Foundations
- Create KMP spec project tree under `specs/projects/kmp/`.
- Add `ARCHITECTURE.md` and `INITIATIVE.md` skeletons.
- Publish `INDEX.md` as the KMP entrypoint.
Exit criteria:
- KMP entry docs exist and are linked from `specs/README.md`.
### Phase 2: Command Taxonomy
- Add new namespaced KMP commands to root `package.json`.
- Add compatibility aliases from old `kmp:*` commands.
- Document command matrix (`task -> command -> expected output`).
Exit criteria:
- All existing KMP workflows work through new commands.
### Phase 3: Package Folder Rename
- Rename folder `packages/kmp-test-app` to `packages/kmp-sdk-test-app`.
- Keep workspace package name as `@selfxyz/kmp-test-app`.
- Update all path references in scripts, Gradle settings, docs, and specs.
Exit criteria:
- No path references remain to `packages/kmp-test-app`.
- Workspace package name remains unchanged.
### Phase 4: Spec Migration
- Move KMP-relevant specs into `specs/projects/kmp/` buckets.
- Add compatibility index in root `specs/README.md` mapping old paths to new paths.
- Add `KMP-CHANGELOG.md` and `KMP-DECISIONS.md`.
Exit criteria:
- KMP spec navigation starts at one path and old references are redirected.
### Phase 5: Deprecation Cleanup
- Remove old command aliases after signoff window.
- Remove transitional links once references converge.
- Run full lint/types/build/tests for impacted workspaces.
Exit criteria:
- No transitional aliases or duplicate KMP spec locations remain.
## Risks and Mitigations
1. Broken references after rename
- Mitigation: perform repo-wide search/replace + validation pass before merge.
2. Temporary confusion during command transition
- Mitigation: keep aliases and publish command matrix with examples.
3. Spec drift after migration
- Mitigation: add `Last verified` and heading-validator checks in CI.
## Validation Checklist
- `yarn lint`
- `yarn types`
- `yarn build`
- `yarn test`
- `rg -n "packages/kmp-test-app" .`
- `rg -n "specs/projects/kmp" specs/README.md`
## Immediate Next Actions
1. Create architecture and initiative doc skeletons in `specs/projects/kmp/`.
2. Add new root KMP command taxonomy with alias compatibility.
3. Prepare and execute package folder rename in one focused PR.
4. Migrate KMP specs and add redirect mapping.

0
specs/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md → specs/framework/PRODUCT-SPEC-ENHANCEMENT-PROMPT.md
View File

131
specs/TEMPLATES.md → specs/framework/TEMPLATES.md
View File

@@ -2,11 +2,11 @@
Three copy-paste templates. Pick the one that matches what you're writing.
| Template | When to use | Output file |
| ---------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- |
| [Project Overview](#project-overview-template) | One per project. System-level architecture. Changes rarely. | `specs/SDK-OVERVIEW.md` |
| [Workstream Overview](#workstream-overview-template) | One per person/workstream. Orientation for new devs. Changes occasionally. | `specs/person-*/OVERVIEW.md` |
| [Implementation Spec](#implementation-spec-template) | One per person/workstream. Detailed build instructions. Changes frequently. | `specs/person-*/SPEC.md` |
| Template | When to use | Output file |
| ---------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------- |
| [Project Overview](#project-overview-template) | One per project. System-level architecture. Changes rarely. | `specs/<project>/OVERVIEW.md` |
| [Workstream Overview](#workstream-overview-template) | Orientation context. Merge as `## Context` section into SPEC.md. | Merged into `workstreams/<scope>/SPEC.md` |
| [Implementation Spec](#implementation-spec-template) | One per person/workstream. Detailed build instructions. Changes frequently. | `specs/<project>/workstreams/<scope>/SPEC.md` |
---
@@ -20,14 +20,6 @@ Three copy-paste templates. Pick the one that matches what you're writing.
> Owner: [name/team]
> Status: [Draft | Active | Complete]
### Required References
<!-- Keep these links intact so spec authors always read the right context.
This IS the project overview, so don't link it to itself.
Workstream/impl specs link back here; this links to rules only. -->
- [PROJECT-RULES.md](./PROJECT-RULES.md)
### North Star
<!-- Bullet-point list. Why does this project exist? What does success look
@@ -46,10 +38,6 @@ like? Use 2-4 bullets for easy scanning, not a paragraph. -->
- [ ] [Milestone]
- [ ] Integration: [target]
### Rules Reminder
Apply [PROJECT-RULES.md](./PROJECT-RULES.md) — especially **Reuse & Maintainability** for UI work, **Architecture** for native/bridge work, and **Quality/Planning** for checklist and plan discipline. Prefer repo validation commands and note that token-sized chunks and LOC-sized PRs are different constraints.
### Architecture Diagram
<!-- ASCII diagram of the full system. Single most important element.
@@ -102,15 +90,15 @@ This is the single source of truth that all workstreams build against. -->
### Workstreams
<!-- Who does what. Link to each person's overview and implementation spec. -->
<!-- Who does what. Link to each person's implementation spec. -->
```
Person 1 — [Scope] -> person1-scope/OVERVIEW.md | person1-scope/SPEC.md
Person 1 — [Scope] -> workstreams/<scope>/SPEC.md
|- [deliverable]
|- [deliverable]
'- [deliverable]
Person 2 — [Scope] -> person2-scope/OVERVIEW.md | person2-scope/SPEC.md
Person 2 — [Scope] -> workstreams/<scope>/SPEC.md
|- [deliverable]
'- [deliverable]
```
@@ -149,24 +137,6 @@ would confuse a new dev or AI agent. -->
| ------ | ------------ |
| [term] | [definition] |
### Related Specs
<!-- Link to every workstream overview, implementation spec, and integration spec. -->
| Spec | Audience | What it covers |
| -------------------------------------------------------- | ----------- | -------------- |
| [person1-scope/OVERVIEW.md](./person1-scope/OVERVIEW.md) | Dev joining | [scope] |
| [person1-scope/SPEC.md](./person1-scope/SPEC.md) | Implementer | [scope] |
### Spec Deviations
<!-- If this spec intentionally skips strong suggestions from SPEC-GUIDE.md,
document which ones and why. Remove this section if none. -->
| Suggestion skipped | Reason |
| ------------------ | ------ |
| [suggestion] | [why] |
---
# Workstream Overview Template
@@ -177,21 +147,13 @@ document which ones and why. Remove this section if none. -->
> Last updated: [date]
> Owner: [name]
> Project: [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Implementation: [SPEC.md](./SPEC.md)
> Project: `../OVERVIEW.md`
> Implementation: `./SPEC.md`
> Status: [Draft | Active | Complete]
### Required References
<!-- Keep these links intact so spec authors always read the right context. -->
- [PROJECT-RULES.md](../PROJECT-RULES.md)
- [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) (if this project has a project overview, link it here)
### North Star
<!-- Same project-level north star from the project overview. Repeated so
the reader has context without navigating up. 2-4 bullets. -->
<!-- Same project-level north star from the project overview. 2-4 bullets. -->
- [Business/product goal — why this exists]
- [Success metric — measurable outcome]
@@ -199,18 +161,12 @@ the reader has context without navigating up. 2-4 bullets. -->
### Status
<!-- High-level milestones for this workstream. Mirrors the chunking
in SPEC.md but at a summary level. This is the FIRST thing devs check —
keep it at the top. -->
<!-- High-level milestones for this workstream. -->
- [x] [milestone]
- [ ] [milestone]
- [ ] [milestone]
### Rules Reminder
Apply [PROJECT-RULES.md](../PROJECT-RULES.md) — especially **Reuse & Maintainability** for UI work, **Architecture** for native/bridge work, and **Quality/Planning** for checklist and plan discipline. Prefer repo validation commands and note that token-sized chunks and LOC-sized PRs are different constraints.
### What You Own
<!-- 3-5 bullets. What packages, deliverables, and outputs does this
@@ -222,8 +178,8 @@ workstream produce? Keep it scannable — details live in SPEC.md. -->
### Architecture Context
<!-- Focused diagram showing where THIS person's work fits in the larger
system. Highlight what this person builds vs what they consume from others.
<!-- Focused diagram showing where THIS workstream's work fits in the larger
system. Highlight what this workstream builds vs what it consumes from others.
Keep it simpler than the project-level diagram — just enough context. -->
```
@@ -235,10 +191,10 @@ Keep it simpler than the project-level diagram — just enough context. -->
<!-- What you need from other workstreams and what they need from you.
Update status as work progresses. -->
| Direction | Person / Package | What | Status |
| ------------- | ---------------- | ---------------------------- | ------- |
| **You need** | Person X | [what you consume from them] | [state] |
| **Needs you** | Person Y | [what they consume from you] | [state] |
| Direction | Workstream / Package | What | Status |
| ------------- | -------------------- | ---------------------------- | ------- |
| **You need** | [scope] | [what you consume from them] | [state] |
| **Needs you** | [scope] | [what they consume from you] | [state] |
### Key Decisions
@@ -257,23 +213,6 @@ decision matrix for system-wide decisions. -->
| -------------------- | --------------- | ------------- |
| [package / artifact] | [npm / AAR / …] | [who uses it] |
### Related Specs
| Spec | What it covers |
| ------------------------------------------------ | ----------------------------------------------------- |
| [SPEC.md](./SPEC.md) | Implementation details, chunks, code changes |
| [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Project-level architecture, bridge protocol, glossary |
| [../personX/OVERVIEW.md](../personX/OVERVIEW.md) | [dependency context] |
### Spec Deviations
<!-- If this spec intentionally skips strong suggestions from SPEC-GUIDE.md,
document which ones and why. Remove this section if none. -->
| Suggestion skipped | Reason |
| ------------------ | ------ |
| [suggestion] | [why] |
---
# Implementation Spec Template
@@ -284,21 +223,9 @@ document which ones and why. Remove this section if none. -->
> Last updated: [date]
> Owner: [name]
> Parent: [OVERVIEW.md](./OVERVIEW.md)
> Parent: `../OVERVIEW.md`
> Status: [Draft | Active | Complete]
### Required References
<!-- Keep these links intact so spec authors always read the right context. -->
- [PROJECT-RULES.md](../PROJECT-RULES.md)
- [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) (if this project has a project overview, link it here)
- [OVERVIEW.md](./OVERVIEW.md)
### Rules Reminder
Apply [PROJECT-RULES.md](../PROJECT-RULES.md) — especially **Reuse & Maintainability** for UI work, **Architecture** for native/bridge work, and **Quality/Planning** for checklist and plan discipline. Include relevant constraints in each chunk's "You will NOT" section, prefer repo validation commands, and note that token-sized chunks and LOC-sized PRs are different constraints.
### North Star
<!-- Bullet-point list of what success looks like. Same project-level north
@@ -320,7 +247,7 @@ This matters because [context]." -->
- Familiarity with [pattern/tool/concept]
- [Term] = [definition]
- Read [OVERVIEW.md](./OVERVIEW.md) for workstream context
- Read the `## Context` section in this `SPEC.md` for workstream context
### The Problem
@@ -369,8 +296,8 @@ CREATE for new files. Every task needs I/O with at least one edge case. -->
##### Input / Output
<!-- Use whichever format matches the interface. See SPEC-GUIDE.md for
format examples: API, bridge message, function, state machine, config, UI. -->
<!-- Use whichever format matches the interface:
API, bridge message, function, state machine, config, UI. -->
**Input:**
@@ -544,12 +471,6 @@ Chunk A (no deps)
[integration check command]
```
### Coordination Notes
<!-- Who needs to know what, and when. -->
- **[Person/Team]:** [what they need from you or you from them]
### Key Reference Files
| File | What to Look At |
@@ -593,11 +514,3 @@ Chunk A (no deps)
| Item | Discovered during | Suggested spec |
| ------- | ----------------- | ---------------------- |
| [thing] | Chunk [ID] | [new or existing spec] |
### Spec Deviations
<!-- Strong suggestions from SPEC-GUIDE.md that were intentionally skipped. -->
| Suggestion skipped | Reason |
| ------------------ | ------ |
| [suggestion] | [why] |

100
specs/person1-webview/OVERVIEW.md
View File

@@ -1,100 +0,0 @@
# Person 1: WebView UI + Bridge — Workstream Overview
> Last updated: 2026-02-23
> Owner: Person 1 (WebView UI + Bridge)
> Project: [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Implementation: [SPEC.md](./SPEC.md)
> Status: Active
## North Star
- **Goal:** Embed Self's identity verification into any host app with zero duplicated logic across platforms.
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Status
- [x] Bridge protocol types and `WebViewBridge` class (63 tests pass)
- [x] Bridge adapters: NFC, auth, storage, lifecycle, crypto (sign + hash)
- [x] Web fallback adapters: IndexedDB documents, Web Crypto, console analytics, navigation, haptic
- [x] Mock transport (`MockNativeBridge`) for testing
- [x] Schema validation for bridge messages
- [x] All 10 screens built and routing works
- [x] BridgeProvider and SelfClientProvider wired
- [x] Biometrics bridge adapter wired in `SelfClientProvider`
- [x] Camera bridge adapter wired in `SelfClientProvider`
- [x] Fallback wiring reconciled in `SelfClientProvider` (`haptic` uses web no-op)
- [x] Hybrid crypto contract signed off (`hash` in WebView, `sign` via native bridge)
- [ ] Dynamic proof request items are still hardcoded in `ProvingScreen`
## What You Own
- **`@selfxyz/webview-bridge`** — Bridge protocol library (public npm). Pure TypeScript, no react-native imports. Defines the JSON messaging protocol, `WebViewBridge` class, bridge adapters (NFC, auth, storage, lifecycle, crypto), and web fallback adapters (IndexedDB documents, Web Crypto hashing, console analytics).
- **`@selfxyz/webview-app`** — Vite-bundled React app (bundled into native SDKs). 10 screens, Tamagui UI, React Router, BridgeProvider, SelfClientProvider. The output of `vite build` is a single `dist/index.html` + JS bundle that ships to every host app.
- **Web fallback adapters** — IndexedDB for documents, Web Crypto for hashing, console/fetch for analytics, React Router for navigation, no-op for haptic. These run entirely in the browser with no bridge round-trip.
- **All 10 WebView screens** — Country picker, ID selection, document camera, NFC scan, confirm identification, proving, verification result, home, settings, coming soon.
## Architecture Context
You build the middle two layers: the bridge protocol library and the WebView UI. Native shells sit above you; the SDK engine sits below you.
```
┌──────────────────────────────────────────────────┐
│ NATIVE SHELLS (Person 2 / 5) │
│ KMP (Android + iOS) | RN (react-native-webview)│
│ 5 native handlers: NFC, Camera, Bio, Key, Life │
└──────────────────────┬───────────────────────────┘
│ postMessage (JSON)
┌─────────────▼──────────────┐
│ @selfxyz/webview-bridge │ ◄── YOU BUILD THIS
│ Bridge protocol + adapters │
└─────────────┬──────────────┘
│
┌─────────────▼──────────────┐
│ @selfxyz/webview-app │ ◄── YOU BUILD THIS
│ 10 screens, providers, │
│ Vite bundle (dist/) │
└─────────────┬──────────────┘
│ imports adapters + hooks
┌─────────────▼──────────────┐
│ @selfxyz/mobile-sdk-alpha │ (Person 4)
│ Proving machine, stores, │
│ adapter interfaces │
└────────────────────────────┘
```
## Dependencies
| Direction | Person / Package | What | Status |
| ------------- | ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------ |
| **You need** | Person 4 (`mobile-sdk-alpha`) | Adapter interfaces, `useSelfClient()` hook, color/font constants | Active |
| **You need** | Person 2 (KMP / Swift shells) | Native handler implementations on the other side of the bridge | Implemented (contract alignment follow-up) |
| **Needs you** | Person 2 (KMP / Swift shells) | Vite bundle (`dist/index.html` + JS) embedded into native SDK artifacts | Ready |
| **Needs you** | Person 5 (RN SDK) | Same Vite bundle loaded via `react-native-webview` | In progress |
## Key Decisions
| Decision | Choice | Rationale |
| ------------------------------------ | ------------------------- | ----------------------------------------------------------------- |
| No react-native in bridge | Pure TypeScript | Bridge works in any browser; RN alias lives only in Vite config |
| Web-first, bridge only when forced | Web APIs for 5/10 domains | Fewer round-trips, no native work for things the browser handles |
| Single bundle, zero external fetches | Vite inlines everything | `dist/` is self-contained; no CDN, no external scripts |
| Screen parity with RN app | Pixel-level match | RN screens are the design reference; Tamagui + same fonts/colors |
| Native handlers are dumb pipes | Zero business logic | Adapters serialize/deserialize; logic lives in `mobile-sdk-alpha` |
## Deliverables
| Deliverable | Type | Consumers |
| --------------------------- | ------------------------------------ | ----------------------------------------------------------------- |
| `@selfxyz/webview-bridge` | Public npm package | `webview-app`, Person 2 (test mocks), Person 5 |
| `@selfxyz/webview-app` dist | Vite bundle (`dist/index.html` + JS) | Person 2 (bundled into KMP SDK), Person 5 (loaded via RN WebView) |
## Related Specs
| Spec | What it covers |
| ---------------------------------------------------------------------------- | ----------------------------------------------------- |
| [SPEC.md](./SPEC.md) | Implementation details, chunks, code changes, tests |
| [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Project-level architecture, bridge protocol, glossary |
| [../person2-native-shells/OVERVIEW.md](../person2-native-shells/OVERVIEW.md) | Native shells workstream — your bridge consumers |
| [../person4-sdk-core/OVERVIEW.md](../person4-sdk-core/OVERVIEW.md) | SDK core workstream — your adapter interface source |
| [../person5-rn-sdk/OVERVIEW.md](../person5-rn-sdk/OVERVIEW.md) | RN SDK workstream — loads your Vite bundle |

119
specs/person2-native-shells/OVERVIEW.md
View File

@@ -1,119 +0,0 @@
# Person 2: Native Shells (KMP SDK + Swift Providers) — Workstream Overview
> Last updated: 2026-02-23
> Owner: Person 2 (Native Shells)
> Project: [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Implementation: [SPEC.md](./SPEC.md)
> Status: Active
## North Star
- **Goal:** Embed Self's identity verification into any host app with zero duplicated logic across platforms.
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Status
- [x] KMP module structure with `expect`/`actual` pattern
- [x] Android WebView host + Activity
- [x] Android handlers: NFC, Camera, Biometrics, Keychain, Lifecycle (5 of 5)
- [x] Bridge message routing (`MessageRouter`)
- [x] Delete 4 unnecessary Android handlers (documents, crypto, analytics, haptic — 511 LOC)
- [x] iOS Swift providers are implemented and wired (NFC, Biometrics, Lifecycle, WebView host + additional providers)
- [x] `SelfSdk.launch()` flow is implemented on iOS
- [x] Shared KMP validation baseline captured (`:shared:compileKotlinIosSimulatorArm64` + `:shared:jvmTest` successful)
- [x] KMP test app validation on both platforms completed (Android assemble + iOS compile)
- [x] Platform asymmetry contract documented and signed off (iOS 9-handler superset vs Android 5-handler core set)
- [x] MiniPay sample integration is wired (`SelfSdk.launch()` call path present)
## What You Own
- `packages/kmp-sdk/` — Kotlin Multiplatform SDK (Android + iOS targets)
- `packages/self-sdk-swift/` — Swift companion package for iOS providers
- Android native handlers (NFC, Camera, Biometrics, Keychain, Lifecycle)
- iOS native handlers (via Swift provider pattern — no cinterop)
- `SelfSdk.launch()` public API for host apps
- WebView hosting (Android `WebView` + iOS `WKWebView`)
## Architecture Context
You build the native shells that sit between the host app and the bridge protocol. Your code hosts the WebView, intercepts bridge messages, and routes them to platform APIs.
```
┌──────────────────────────────────────────────────┐
│ HOST APP │
│ (MiniPay / Self Wallet / etc.) │
│ │
│ SelfSdk.launch(request, callback) │
└────────────────────┬─────────────────────────────┘
│
┌────────────────▼────────────────┐
│ YOUR LAYER (Person 2) │
│ │
│ ┌───────────┐ ┌────────────┐ │
│ │ Android │ │ iOS │ │
│ │ kmp-sdk │ │ kmp-sdk + │ │
│ │ (Kotlin) │ │ Swift pkg │ │
│ └─────┬─────┘ └──────┬─────┘ │
│ │ Android: 5 │ │
│ │ iOS: 9 * │ │
│ NFC · Camera · Biometrics │
│ Keychain · Lifecycle │
│ │ │ │
│ ┌─────▼───────────────▼─────┐ │
│ │ WebView Host │ │
│ │ (loads Person 1 bundle) │ │
│ └─────────────┬─────────────┘ │
└────────────────┼────────────────┘
│ JSON postMessage
┌────────────────▼────────────────┐
│ BRIDGE PROTOCOL (Person 1) │
│ webview-bridge │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ WEBVIEW UI (Person 1) │
│ webview-app Vite bundle │
└─────────────────────────────────┘
* iOS implementation now registers 9 handlers (NFC, Camera, Biometrics, SecureStorage, Lifecycle, Documents, Crypto, Analytics, Haptic); Android remains focused on 5 core native handlers. This asymmetry is now explicitly accepted as a compatibility superset contract: Android is the normative minimum, iOS extra handlers must remain behavior-compatible and non-authoritative for web-fallback domains.
```
## Dependencies
| Direction | Person / Package | What | Status |
| ------------- | ---------------- | --------------------------------------------------- | ------------ |
| **You need** | Person 1 | Vite bundle (`dist/`) loaded into your WebView | In progress |
| **You need** | Person 1 | Bridge protocol types (`@selfxyz/webview-bridge`) | Ready |
| **Needs you** | Person 5 | Bridge protocol as reference for RN handler pattern | Ready |
| **Needs you** | Integrations | `SelfSdk.launch()` API consumed by MiniPay sample | Android done |
## Key Decisions
| Decision | Choice | Rationale |
| ----------------------------- | --------------------- | -------------------------------------------------------------------------------- |
| cinterop for Apple frameworks | **Disabled** | Xcode SDK compatibility issues. All Apple calls go through Swift providers. |
| 4 extra Android handlers | **Delete** | Web fallbacks replace them (IndexedDB, Web Crypto, console/fetch, skip haptic) |
| iOS provider pattern | **Swift factory** | Swift protocols injected into KMP iOS handlers at init time |
| Swift async bridging | **Callback-based** | Swift closures dispatch to main queue; Kotlin uses `suspendCancellableCoroutine` |
| WebView bundle location | **Bundled in assets** | Person 1's Vite output (`dist/`) copied into app assets at build time |
## Deliverables
| Deliverable | Type | Consumers |
| ---------------------- | ----------- | --------------------------------- |
| KMP SDK artifact | AAR | Android host apps (MiniPay) |
| XCFramework | XCFramework | iOS host apps |
| `SelfSdk.launch()` API | Public API | Any host app calling verification |
| Swift provider package | SPM package | iOS host apps (companion to KMP) |
## Related Specs
| Spec | What it covers |
| -------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [SPEC.md](./SPEC.md) | Implementation details, chunks, code changes |
| [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Project-level architecture, bridge protocol, glossary |
| [../person1-webview/OVERVIEW.md](../person1-webview/OVERVIEW.md) | WebView UI + bridge — delivers the Vite bundle you host |
| [../person4-sdk-core/OVERVIEW.md](../person4-sdk-core/OVERVIEW.md) | SDK core adaptation — delivers adapter interfaces you implement |
| [../person5-rn-sdk/OVERVIEW.md](../person5-rn-sdk/OVERVIEW.md) | RN native shell — mirrors your bridge pattern for React Native |
| [../person3-integrations/OVERVIEW.md](../person3-integrations/OVERVIEW.md) | MiniPay sample — first consumer of your `SelfSdk.launch()` API |

92
specs/person3-integrations/OVERVIEW.md
View File

@@ -1,92 +0,0 @@
# Person 3: Integration Samples — Workstream Overview
> Last updated: 2026-02-23
> Owner: Person 3 (Integrations)
> Project: [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Implementation: [SPEC-MINIPAY-SAMPLE.md](./SPEC-MINIPAY-SAMPLE.md)
> Status: Active
## North Star
- **Goal:** Embed Self's identity verification into any host app with zero duplicated logic across platforms.
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Status
- [x] MiniPay sample project scaffolded (`packages/kmp-minipay-sample/`)
- [x] Android: home screen + SDK launch + result screen wiring present
- [x] iOS: Compose Multiplatform launch path is present
- [x] Integration hardening paths are implemented in sample result UX (error-code to user-message mapping)
- [x] Non-device validation evidence captured:
- `@selfxyz/rn-sdk` tests: all passing at merge time (includes NFC failure modes and APDU path handling; see CI checks)
- `@selfxyz/webview-bridge` tests: all passing at merge time (see CI checks)
- iOS launch E2E artifact: `app/maestro-results.xml` (1 test, 0 failures, 19s on iPhone 16 simulator)
Overall: **Done** — implementation and non-device validation are in place. Physical-device NFC E2E is out of scope (requires NFC hardware, real passport, camera, biometrics — not automatable in CI).
## What You Own
- **MiniPay sample app** (`packages/kmp-minipay-sample/`) — Kotlin/Compose Multiplatform reference integration
- **Future integration samples** — Self Wallet migration sample, other third-party app examples as needed
- **Reference implementation quality code** — what third-party integrators will copy when they embed Self
## Architecture Context
Your sample apps sit **on top of** the SDK. You consume `SelfSdk.launch()` and nothing else. The entire verification flow runs inside the SDK's WebView. Your native UI is minimal: 2 screens (home + result).
```
┌────────────────────────────────────────┐
│ Sample App (Compose Multiplatform) │
│ │
│ HomeScreen ──→ SelfSdk.launch() ──→ ResultScreen
│ (native) (SDK WebView) (native)
└────────────────────┬───────────────────┘
│
┌───────────▼───────────┐
│ KMP SDK (kmp-sdk/) │
│ 5 native handlers │
│ WebView host │
│ Bridge protocol │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ WebView (Vite bundle)│
│ Full verification │
│ flow: 10 screens │
└───────────────────────┘
```
## Dependencies
| Direction | Person / Package | What | Status |
| ------------- | ----------------------- | -------------------------------------------------- | ----------- |
| **You need** | Person 2 (KMP SDK) | `SelfSdk.launch()` API and Kotlin SDK artifact | In progress |
| **You need** | Person 1 (WebView UI) | Vite bundle embedded in the SDK | In progress |
| **Needs you** | Third-party integrators | Reference implementation showing how to embed Self | Not started |
## Key Decisions
| Decision | Choice | Rationale |
| --------------------- | -------------------------- | ------------------------------------------------------------- |
| Native UI scope | 2 screens (home + result) | Demonstrates that integrators write almost no UI code |
| SDK call site | Single: configure + launch | Keeps integration surface area minimal and copyable |
| Code quality standard | Reference quality | Third-party developers will copy this code directly |
| Platform parity | Android + iOS identical | Shared Kotlin handles all logic; platform code = entry points |
## Deliverables
| Deliverable | Type | Consumers |
| ------------------------- | ------------------------------- | ----------------------- |
| MiniPay sample app | KMP app (`kmp-minipay-sample/`) | Third-party integrators |
| Integration documentation | By-example (in the code) | Third-party integrators |
## Related Specs
| Spec | What it covers |
| ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| [SPEC-MINIPAY-SAMPLE.md](./SPEC-MINIPAY-SAMPLE.md) | Implementation details, chunks, code changes |
| [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Project-level architecture, bridge protocol, glossary |
| [../person1-webview/OVERVIEW.md](../person1-webview/OVERVIEW.md) | WebView UI + bridge workstream (delivers the Vite bundle) |
| [../person2-native-shells/OVERVIEW.md](../person2-native-shells/OVERVIEW.md) | KMP SDK workstream (delivers the artifact you depend on) |
| [../person4-sdk-core/OVERVIEW.md](../person4-sdk-core/OVERVIEW.md) | SDK core workstream (adapter interfaces, web fallbacks) |
| [../person5-rn-sdk/OVERVIEW.md](../person5-rn-sdk/OVERVIEW.md) | RN SDK workstream (alternative native shell for RN hosts) |

108
specs/person4-sdk-core/OVERVIEW.md
View File

@@ -1,108 +0,0 @@
# Person 4: SDK Core Adaptation — Workstream Overview
> Last updated: 2026-02-23
> Owner: Person 4 (SDK Core)
> Project: [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Implementation: [SPEC.md](./SPEC.md)
> Status: Active
## North Star
- **Goal:** Embed Self's identity verification into any host app with zero duplicated logic across platforms.
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Status
- [x] 275+ tests passing
- [x] React Native adapters built and working
- [x] Config & Platform Abstraction (Chunk 4A — Done)
- [x] Browser Entry Point & Package Exports (Chunk 4B — Done)
- [x] WebView Lifecycle Events (Chunk 4C — Done)
- [x] Conditional SelfApp Store (Chunk 4E — Done)
- [x] Web Fallback Adapter Implementations (Chunk 4F — Done)
- [x] Fallback ownership decision documented (`mobile-sdk-alpha` owns WebView-only fallback logic)
- [x] Web-only fallback vs bridge-routing contract documented (hybrid crypto + no-op haptic)
- [ ] Implementation consolidation still pending (bridge-layer fallback duplicates not yet fully removed)
- [ ] `generateKey()`/`getPublicKey()` not exposed in `BridgeCryptoAdapter` interface — methods exist in iOS native handler and bridge protocol types but unreachable from WebView client code
## What You Own
- **`@selfxyz/mobile-sdk-alpha`** — the WebView engine (proving machine, stores, adapters, document management).
- **Browser entry point** (`src/browser.ts`) — the import path for WebView consumers, with zero `react-native` transitive imports.
- **Web fallback adapter implementations** — IndexedDB for documents, Web Crypto for hashing, console/fetch for analytics.
- **Platform abstraction** for the adapter interfaces — making the engine portable across React Native and browser/WebView contexts.
## Architecture Context
You own the SDK engine layer. It sits below Person 1's WebView UI and above the shared utilities. Your job is to make this engine work identically in both React Native and browser/WebView contexts.
```
┌──────────────────────────────────────┐
│ Person 1: WebView UI │
│ (webview-app, screens, router) │
│ │
│ Consumes: useSelfClient(), stores, │
│ proving machine, adapter interfaces │
└──────────────────┬───────────────────┘
│
╔══════════════╧═══════════════╗
║ Person 4: SDK Engine (YOU) ║
║ (mobile-sdk-alpha) ║
║ ║
║ Proving machine (XState) ║
║ Document store (Zustand) ║
║ Adapter interfaces ║
║ ║
║ Two entry points: ║
║ ├─ src/index.ts (RN) ║
║ └─ src/browser.ts (WebView) ║
║ ║
║ Web fallback adapters: ║
║ ├─ IndexedDB (documents) ║
║ ├─ Web Crypto (hash) ║
║ └─ console/fetch (analytics)║
╚══════════════╤═══════════════╝
│
┌──────────────┴───────────────┐
│ Shared Utilities │
│ (common/) │
│ Poseidon, Merkle, MRZ, certs│
└──────────────────────────────┘
```
## Dependencies
| Direction | Person / Package | What | Status |
| ------------- | ---------------- | --------------------------------------------------------------------------- | ----------- |
| **You need** | Nobody | Your work is independent in Phase 1 | Ready |
| **Needs you** | Person 1 | Adapter interfaces, core logic (`useSelfClient()`, stores, proving machine) | In progress |
| **Needs you** | Person 2 | Web fallback adapters to confirm which bridge domains are unnecessary | Pending |
| **Needs you** | Person 5 | Browser entry point working in RN WebView context | Pending |
## Key Decisions
| Decision | Choice | Rationale |
| --------------------------------- | ------------------------ | ------------------------------------------------------------------ |
| Adapter interface design | Keep as-is | Already right — don't redesign, just remove platform contamination |
| Keychain / SecureStorage | Always bridges to native | Security boundary — host app controls access |
| Documents, crypto hash, analytics | Web fallback adapters | Eliminates unnecessary bridge round-trips |
| Proving machine + adapter arch | Don't refactor | They work — you are removing contamination, not redesigning |
| `@selfxyz/common` issues | Out of scope | If Buffer or Node-specific issues exist, file separately |
## Deliverables
| Deliverable | Type | Consumers |
| --------------------------------------------------------- | ------------------- | ----------------------------------------- |
| `@selfxyz/mobile-sdk-alpha` (clean browser entry) | npm package | Person 1 (webview-app), Person 5 (rn-sdk) |
| Web fallback adapters (documents, crypto hash, analytics) | Source (in package) | Person 1 (SelfClientProvider wiring) |
## Related Specs
| Spec | What it covers |
| ---------------------------------------------------------------------------- | ----------------------------------------------------- |
| [SPEC.md](./SPEC.md) | Implementation details, chunks, code changes |
| [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Project-level architecture, bridge protocol, glossary |
| [../person1-webview/OVERVIEW.md](../person1-webview/OVERVIEW.md) | WebView UI — your primary consumer |
| [../person2-native-shells/OVERVIEW.md](../person2-native-shells/OVERVIEW.md) | Native shells — consumes your web fallback signals |
| [../person5-rn-sdk/OVERVIEW.md](../person5-rn-sdk/OVERVIEW.md) | RN SDK — consumes your browser entry point |

122
specs/person5-rn-sdk/OVERVIEW.md
View File

@@ -1,122 +0,0 @@
# Person 5: RN Native Shell — Workstream Overview
> Last updated: 2026-02-23
> Owner: Person 5 (RN SDK)
> Project: [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Implementation: [SPEC.md](./SPEC.md)
> Status: Active
## North Star
- **Goal:** Embed Self's identity verification into any host app with zero duplicated logic across platforms.
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Status
- [x] Package scaffolding exists (`packages/rn-sdk/`, package config, tsconfig, tsup)
- [x] `SelfVerification` component with `react-native-webview` is implemented
- [x] `MessageRouter` dispatching bridge messages to handlers is implemented
- [x] 5 native handler bridges are implemented (NFC, Camera, Biometrics, Keychain, Lifecycle)
- [x] Asset loading strategy is implemented for iOS + Android, including dev override
- [x] NFC handler supports APDU command exchange (`apduCommands` -> `apduResponses`)
- [x] Camera MRZ bridge is implemented against native scanner modules
- [ ] Integration validation in Self Wallet app is still a follow-up validation task
- [ ] npm publish (`@selfxyz/rn-sdk`) not completed in this branch
**Overall: Partial** — package implementation is present; highest-risk carry-forward item is breadth of physical-device integration validation across host apps.
## What You Own
- **`@selfxyz/rn-sdk`** — the React Native SDK package
- **`SelfVerification`** component (~200-300 LOC) — the single public API surface
- **5 native handler bridges** — NFC, Camera, Biometrics, Keychain, Lifecycle (thin wrappers around RN native modules)
- **Asset bundling** — Vite bundle loaded into `react-native-webview` on iOS + Android via `Platform.select`
## Architecture Context
You are building a thin React Native wrapper that hosts the exact same WebView as Person 2's Kotlin/Swift shell. Same bridge protocol, same Vite bundle, different native shell.
```text
┌─────────────────────────────────────────┐
│ HOST APP (React Native) │
│ (Self Wallet / third-party) │
│ │
│ <SelfVerification │
│ userId="..." │
│ disclosures={[...]} │
│ onComplete={handleResult} │
│ /> │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ ★ YOUR LAYER: @selfxyz/rn-sdk │
│ (~200-300 LOC total) │
│ │
│ SelfVerification.tsx │
│ └─ react-native-webview │
│ ├─ onMessage → MessageRouter │
│ └─ injectJavaScript ← responses │
│ │
│ MessageRouter.ts │
│ ├─ NfcHandler (rn-nfc-manager) │
│ ├─ CameraHandler (rn-camera) │
│ ├─ BiometricsHandler(rn-biometrics) │
│ ├─ KeychainHandler (rn-keychain) │
│ └─ LifecycleHandler(props callbacks) │
└──────────────┬──────────────────────────┘
│ postMessage (JSON)
│ Same bridge protocol as KMP
┌──────────────▼──────────────────────────┐
│ SHARED WEBVIEW (Person 1 + 4) │
│ Vite bundle: webview-app + engine │
│ Same dist/ loaded by KMP and RN shells │
└─────────────────────────────────────────┘
```
The WebView does not know which native shell it is running inside. Your handlers implement the same domain/method/params contract as the Kotlin handlers.
## Dependencies
| Direction | Person / Package | What | Status |
| ------------- | --------------------------- | --------------------------------------------------- | ----------- |
| **You need** | Person 1 (`webview-app`) | Vite bundle (`dist/`) — same one KMP uses | In progress |
| **You need** | Person 1 (`webview-bridge`) | Bridge protocol types (`@selfxyz/webview-bridge`) | In progress |
| **You need** | Person 2 (`kmp-sdk`) | Handler pattern as reference (same bridge contract) | In progress |
| **Needs you** | Self Wallet app | `SelfVerification` for verification flow (Phase 2) | Not started |
## Design Principles
1. **Thin wrapper only.** The RN SDK is ~200-300 LOC. All logic lives in the WebView engine (`mobile-sdk-alpha`). If you're writing business logic in this package, you're doing it wrong.
2. **Same bridge protocol as KMP.** The RN handlers implement the exact same domain/method/params contract as the Kotlin handlers. The WebView does not know which native shell it's running in.
3. **Peer dependencies for native modules.** Every React Native native module is a `peerDependency`. The host app installs and links them. This avoids version conflicts and duplicate native code.
4. **No state beyond routing.** The `MessageRouter` dispatches messages and returns responses. It does not cache, retry, or transform data. Handlers are stateless wrappers around native libraries.
## Key Decisions
| Decision | Choice | Rationale |
| --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Package size | Thin wrapper (~200-300 LOC) | All logic lives in the WebView engine. Native shell is pure glue. |
| Bridge protocol | Same as KMP | WebView must not know which shell it runs in. One protocol, two shells. |
| Native module dependency strategy | All as `peerDependencies` | Host app installs and links. Avoids version conflicts and duplicate native code. |
| Asset loading | `Platform.select` for Android vs iOS | Android uses `file:///android_asset/`, iOS path TBD (see Chunk 5D). |
| State management | No state beyond routing | MessageRouter dispatches and returns. No caching, retrying, or transforming. |
| iOS asset loading | Implemented in current package | Uses RNFS main bundle path when available, with documented fallback and manual host bundling requirements. |
## Deliverables
| Deliverable | Type | Consumers |
| ---------------------------- | --------------- | ------------------------------------- |
| `@selfxyz/rn-sdk` | npm package | Self Wallet app, third-party RN hosts |
| `SelfVerification` component | React component | Any RN app embedding verification |
## Related Specs
| Spec | What it covers |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [SPEC.md](./SPEC.md) | Implementation details, chunks, code changes |
| [../SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Project-level architecture, bridge protocol, glossary |
| [../person1-webview/OVERVIEW.md](../person1-webview/OVERVIEW.md) | WebView UI + bridge workstream (delivers your Vite bundle + bridge types) |
| [../person2-native-shells/OVERVIEW.md](../person2-native-shells/OVERVIEW.md) | KMP native shell workstream (reference handler pattern) |
| [../person3-integrations/OVERVIEW.md](../person3-integrations/OVERVIEW.md) | Integration samples (MiniPay — validates the SDK) |
| [../person4-sdk-core/OVERVIEW.md](../person4-sdk-core/OVERVIEW.md) | SDK core workstream (delivers adapter interfaces) |

23
specs/projects/sdk/INDEX.md Normal file
View File

@@ -0,0 +1,23 @@
# SDK Project
Last updated: March 5, 2026
Status: Active
## Start Here
1. [SDK Overview](./OVERVIEW.md) — architecture, bridge protocol, module table, execution status
## Workstreams
| Workstream | Spec |
| ------------- | --------------------------------------------------------- |
| WebView UI | [WebView Spec](./workstreams/webview/SPEC.md) |
| Native Shells | [Native Shells Spec](./workstreams/native-shells/SPEC.md) |
| Integrations | [MiniPay Sample Spec](./workstreams/integrations/SPEC.md) |
| SDK Core | [SDK Core Spec](./workstreams/sdk-core/SPEC.md) |
| RN SDK | [RN SDK Spec](./workstreams/rn-sdk/SPEC.md) |
## Related
- [Euclid Web Consolidation](../../topics/EUCLID-WEB-CONSOLIDATION.md) — WebView convergence plan
- [Security Hardening](../../topics/SECURITY-HARDENING.md) — security follow-ups

69
specs/SDK-OVERVIEW.md → specs/projects/sdk/OVERVIEW.md
View File

@@ -430,11 +430,11 @@ Person 5 — RN Native Shell (NEW) OVERVIEW | SPEC
Links:
- Person 1: [Overview](./person1-webview/OVERVIEW.md) | [Spec](./person1-webview/SPEC.md)
- Person 2: [Overview](./person2-native-shells/OVERVIEW.md) | [Spec](./person2-native-shells/SPEC.md)
- Person 3: [Overview](./person3-integrations/OVERVIEW.md) | [MiniPay Spec](./person3-integrations/SPEC-MINIPAY-SAMPLE.md)
- Person 4: [Overview](./person4-sdk-core/OVERVIEW.md) | [Spec](./person4-sdk-core/SPEC.md)
- Person 5: [Overview](./person5-rn-sdk/OVERVIEW.md) | [Spec](./person5-rn-sdk/SPEC.md)
- Person 1: [Spec](./workstreams/webview/SPEC.md)
- Person 2: [Spec](./workstreams/native-shells/SPEC.md)
- Person 3: [MiniPay Spec](./workstreams/integrations/SPEC.md)
- Person 4: [Spec](./workstreams/sdk-core/SPEC.md)
- Person 5: [Spec](./workstreams/rn-sdk/SPEC.md)
## Input / Output — System Level
@@ -626,25 +626,46 @@ cd app && npx react-native run-ios # integration test
| `common/src/polyfills/crypto.ts` | Cross-platform crypto (noble-hashes) |
| `app/src/providers/selfClientProvider.tsx` | Self Wallet SDK integration (507 lines) |
## Related Specs
## Execution Status
| Spec | Type | Audience | What it covers |
| -------------------------------------------------------------------------------------------- | -------- | -------- | ------------------------------------------------------- |
| [person1-webview/OVERVIEW.md](./person1-webview/OVERVIEW.md) | Overview | Person 1 | WebView workstream orientation, scope, dependencies |
| [person1-webview/SPEC.md](./person1-webview/SPEC.md) | Impl | Person 1 | WebView screens, bridge adapters, SelfClientProvider |
| [person2-native-shells/OVERVIEW.md](./person2-native-shells/OVERVIEW.md) | Overview | Person 2 | Native shells workstream orientation, scope, deps |
| [person2-native-shells/SPEC.md](./person2-native-shells/SPEC.md) | Impl | Person 2 | KMP native shell, Android/iOS handlers, Swift providers |
| [person3-integrations/OVERVIEW.md](./person3-integrations/OVERVIEW.md) | Overview | Person 3 | Integration samples orientation, scope |
| [person3-integrations/SPEC-MINIPAY-SAMPLE.md](./person3-integrations/SPEC-MINIPAY-SAMPLE.md) | Impl | Person 3 | MiniPay integration example |
| [person4-sdk-core/OVERVIEW.md](./person4-sdk-core/OVERVIEW.md) | Overview | Person 4 | SDK core workstream orientation, scope, dependencies |
| [person4-sdk-core/SPEC.md](./person4-sdk-core/SPEC.md) | Impl | Person 4 | SDK core adaptation, RN dep removal, web fallbacks |
| [person5-rn-sdk/OVERVIEW.md](./person5-rn-sdk/OVERVIEW.md) | Overview | Person 5 | RN SDK workstream orientation, scope, dependencies |
| [person5-rn-sdk/SPEC.md](./person5-rn-sdk/SPEC.md) | Impl | Person 5 | RN native shell, `SelfVerification` component |
**Overall: 74% complete** — 23/30 chunks done, 3 partial, 1 skipped, 2 superseded, 1 deferred.
## Spec Deviations
### Remaining Work
| Suggestion skipped | Reason |
| ------------------------ | ------------------------------------------------------------------------------------ |
| Token-budgeted chunks | This is an overview spec (tier 1). Chunks live in the implementation specs (tier 2). |
| BEFORE/AFTER code blocks | No code modifications in scope — this is architecture-level. |
| Definition of Done | Each workstream has its own definition of done in its implementation spec. |
| Chunk | Workstream | Description | Status | Next Step |
| ----- | ------------- | --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| 1E | WebView | WebView App Shell (Vite + router) | Partial | Source dynamic proof request items from `SelfSdk.launch(request)` context instead of hardcoded defaults in ProvingScreen |
| 2F | Native Shells | SDK Public API finalize | Partial | Finalize `SelfSdk.launch()` public API surface after iOS NFC handler (2K) is complete |
| 3C | Integrations | Polish + Error Handling | Partial | Complete error handling polish in MiniPay sample result UX |
| 2L | Native Shells | Camera MRZ Handler (iOS) | Deferred (Phase 2) | Add iOS camera/MRZ via KMP when Phase 2 planning starts. RN SDK has its own implementation via native modules. |
### Open Follow-Up Items
**P1 — Validation Gaps:**
| Item | Owner | Context |
| ----------------------------------------- | -------- | ----------------------------------------------------------- |
| KMP test app validation on both platforms | Person 2 | Compile-verified only; no runtime validation captured |
| Integration validation in Self Wallet app | Person 5 | `SelfVerification` component not yet wired into Self Wallet |
**P2 — Correctness / Consistency:**
| Item | Owner | Context |
| ---------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
| Consolidate duplicated fallback adapters | Person 4 | ~150 LOC duplicated across `webview-bridge` and `mobile-sdk-alpha`. `mobile-sdk-alpha` is canonical. |
| Source dynamic proving request values from request context | Person 1 | `ProvingScreen` accepts params but defaults are hardcoded |
| Expose `generateKey()`/`getPublicKey()` in `BridgeCryptoAdapter` | Person 1/4 | Methods exist in native handler and protocol types but unreachable from WebView client |
**P3 — Publishing / Packaging:**
| Item | Owner | Context |
| ---------------------------------------------- | -------- | ------------------------------------------------------------------- |
| npm publish `@selfxyz/rn-sdk` | Person 5 | Package implemented but not published |
| Production artifact builds (AAR + XCFramework) | Person 2 | KMP SDK packaging for distribution not finalized |
| Self Wallet migration to `SelfVerification` | Person 5 | Phase 2 — replace native verification screens with SDK WebView flow |
### Suggested Follow-Up Order
1. **Correctness cleanup** — Adapter consolidation, dynamic proving config, crypto adapter interface gap
2. **Publishing** — npm publish rn-sdk, finalize AAR/XCFramework packaging
3. **Self Wallet migration** — Wire `SelfVerification` into the main app (Phase 2)

314
specs/projects/sdk/SPEC-AGENT-OPTIMIZATION.md Normal file
View File

@@ -0,0 +1,314 @@
# Agent-Optimized Spec Architecture
> Last updated: 2026-03-05
> Owner: SDK/specs maintainers
> Status: Proposed
## Problem
The current spec system was designed for humans — five workstream OVERVIEWs, five SPECs, a SPEC-GUIDE, TEMPLATES, PROJECT-RULES, a wave plan, and a handoff tracker across 30+ files totaling ~10k lines. This creates three problems for AI agents:
1. **Too many files to read before doing work.** An agent executing chunk 2C must navigate: CLAUDE.md → README → INDEX → OVERVIEW → SPEC → possibly PLAN. That's 6 files before writing a single line of code. Each file read costs context window and latency.
2. **Duplicated context across tiers.** The north star is repeated in OVERVIEW.md, every workstream OVERVIEW.md, and every SPEC.md. The rules reminder is in SPEC-GUIDE, PROJECT-RULES, and every spec header. An agent reads the same information 3-4 times.
3. **Ceremony over signal.** Spec deviations tables, review checklists, "required references" headers, prerequisites glossaries, and related specs tables exist to enforce human process. An agent doesn't need to "run the review checklist" — it needs the chunk scope, files to touch, I/O examples, and a validation command.
### Current file inventory
| Category | Files | Total lines | Agent reads per chunk |
| --------------------------------------------------------------------------------- | ------ | ----------- | --------------------- |
| Framework (SPEC-GUIDE, TEMPLATES, PROJECT-RULES, PRODUCT-SPEC-ENHANCEMENT-PROMPT) | 4 | 1,355 | 0-1 (mostly skipped) |
| SDK project-level (OVERVIEW, PLAN, HANDOFF, STATUS, INDEX) | 5 | 903 | 1-2 |
| Workstream OVERVIEWs (5) | 5 | 541 | 1 |
| Workstream SPECs (5) | 5 | 6,416 | 1 |
| KMP project | 4 | 431 | 0-1 |
| Other (lottie, euclid, ci, shared, archive) | 7 | 704 | 0 |
| **Total** | **30** | **10,350** | **3-5 per chunk** |
### Fake projects add navigation overhead
Four of the five "projects" under `specs/projects/` are not projects — they're either part of SDK or standalone docs wrapped in unnecessary scaffolding:
| "Project" | Real content | Workstreams | Verdict |
| --------- | ------------------------------------------ | ---------------------------------------------------- | ----------------------------- |
| `sdk/` | OVERVIEW + PLAN + HANDOFF + STATUS + INDEX | 5 workstreams with real SPECs | Actual project |
| `kmp/` | 3 skeleton docs (all TBD owners) | None — real work is `sdk/workstreams/native-shells/` | SDK workstream, not a project |
| `lottie/` | INDEX + 1 review doc (58 lines) | None | Standalone doc |
| `euclid/` | INDEX + 1 plan doc (88 lines) | None | Standalone doc |
| `ci/` | 1 coverage gaps doc (313 lines) | None | Standalone doc |
An agent looking for KMP specs navigates to `kmp/INDEX.md`, finds skeleton docs with TBD owners, then gets redirected to `sdk/workstreams/native-shells/` for the real work. The `projects/` nesting adds a directory level that serves no purpose when there's only one real project.
### What an agent actually needs
To execute a chunk, an agent needs exactly:
1. **What to build** — scope, constraints, files in/out of scope
2. **How to validate** — shell commands that prove it works
3. **Current state** — what's done, what's blocked, what's next
4. **Architecture context** — only the parts relevant to this chunk
Everything else is noise.
## Proposed Changes
### Change 1: Merge OVERVIEW into SPEC per workstream
**Before:** 2 files per workstream (OVERVIEW.md + SPEC.md)
**After:** 1 file per workstream (SPEC.md with a "Context" section at top)
The OVERVIEW files are 90-120 lines each. They contain: north star (duplicated from SDK OVERVIEW), "what you own" (3-5 bullets), architecture context diagram, dependencies table, and related specs links. All of this fits as a 30-40 line "Context" section at the top of SPEC.md.
**Why:** One file to read instead of two. The OVERVIEW content rarely changes, so it won't cause merge conflicts with SPEC chunk updates. Agents never read OVERVIEW.md without also reading SPEC.md, so they're always read together anyway.
**Migration:**
- For each workstream, prepend the useful OVERVIEW content (what you own, architecture context, dependencies) as a `## Context` section in SPEC.md
- Drop: north star (already in SPEC), rules reminder (already in CLAUDE.md), related specs table (links are in SPEC already), spec deviations table
- Delete OVERVIEW.md files
- Update INDEX.md workstream table to single column
### Change 2: Consolidate framework docs into CLAUDE.md
**Before:** SPEC-GUIDE.md (335 lines), PROJECT-RULES.md (168 lines), TEMPLATES.md (603 lines) — all in `specs/framework/`
**After:** Key rules in CLAUDE.md (where agents already read them), templates kept as a single reference file
The SPEC-GUIDE and PROJECT-RULES overlap heavily with CLAUDE.md's "Key Rules" and "Specs & Planning" sections. Agents already read CLAUDE.md at session start — it's the one file guaranteed to be in context. Rules that only exist in PROJECT-RULES.md are invisible to agents.
**Migration:**
- Audit PROJECT-RULES.md — any rule not already in CLAUDE.md gets added there
- Audit SPEC-GUIDE.md — the "Writing for AI Agents" section and review checklist move to CLAUDE.md's planning protocol
- TEMPLATES.md stays as-is (it's a copy-paste reference, not agent instructions)
- Archive SPEC-GUIDE.md and PROJECT-RULES.md
- Remove "Required References" and "Rules Reminder" boilerplate from every spec
### Change 3: Flatten the SDK project level
**Before:** INDEX.md + OVERVIEW.md + PLAN.md + HANDOFF.md + STATUS.md (5 files, 903 lines)
**After:** INDEX.md + OVERVIEW.md (2 files, ~750 lines)
- **INDEX.md** stays — it's the entrypoint
- **OVERVIEW.md** stays — architecture diagram + module table + bridge protocol are genuinely useful context
- **PLAN.md** (wave plan) → merge the chunk inventory table into OVERVIEW.md's status section. Before merging, verify all partial/deferred chunks (1E, 2F, 3C, 2L) have clear next-step descriptions in OVERVIEW.md. If any cross-workstream dependencies remain active, preserve the dependency column. Archive the wave sequencing explanation (no longer needed at 74% done).
- **HANDOFF.md** → merge open follow-up items (P1-P3 tables) into OVERVIEW.md's status checklist as "Open" items. Archive the resolved decisions section. Closure gate: every P1 item must have an owner and status before HANDOFF.md is deleted.
- **STATUS.md** (14 lines) → redundant with OVERVIEW.md status checklist. Merge its content into OVERVIEW.md, then delete. Update the canonical path reference in `specs/projects/kmp/INDEX.md` (which currently points to `specs/projects/sdk/STATUS.md` as the relocated SDK-wide status) to point to the OVERVIEW.md status section instead.
### Change 4: Strip ceremony from spec templates
Remove from the TEMPLATES.md spec template:
- "Required References" section (agents read CLAUDE.md, not a references list)
- "Rules Reminder" section (same reason)
- "Spec Deviations" table (process overhead, not agent input)
- "Related Specs" table at bottom (cross-links are useful inline, not as a footer table)
- "Coordination Notes" section (belongs in a task tracker, not a spec)
Keep:
- North star (3 bullets)
- Context section (merged from OVERVIEW)
- Problem table with file:line refs
- Scope of work with I/O examples
- Files in/out of scope
- Chunking guide with validation commands
- Definition of done
- Completion status table
- "What Was Built" appendix (post-completion)
- Follow-up table (parking lot)
### Change 5: Collapse fake projects and flatten hierarchy
**Before:**
```
specs/
projects/
sdk/ <- real project
kmp/ <- skeleton redirecting to sdk/
lottie/ <- INDEX + 1 doc
euclid/ <- INDEX + 1 doc
ci/ <- 1 doc
shared/
handoffs/ <- 1 doc
```
**After:**
```
specs/
sdk/ <- the one real project (drop "projects/" nesting)
INDEX.md
OVERVIEW.md
workstreams/...
topics/ <- standalone docs, no project scaffolding
LOTTIE-DOTLOTTIE-REVIEW.md
EUCLID-WEB-CONSOLIDATION.md
CI-COVERAGE-GAPS.md
SECURITY-HARDENING.md
framework/
archive/
```
**Migration:**
- Move `specs/projects/sdk/` → `specs/sdk/` (drop the `projects/` nesting)
- Move standalone docs into `specs/topics/` with descriptive filenames (no INDEX wrappers)
- Archive KMP skeleton docs (`kmp/ARCHITECTURE.md`, `kmp/INITIATIVE.md`, `kmp/REORG-PLAN.md`, `kmp/INDEX.md`) — the real KMP execution spec is `sdk/workstreams/native-shells/SPEC.md`
- Delete `specs/shared/` (only had one file, now in `topics/`)
- Delete empty `specs/projects/` directory
- Update README.md to flat structure
### Change 6: Add CLAUDE.md spec-reading protocol
Add to CLAUDE.md's planning protocol a concrete reading path:
```
To execute a chunk:
1. Read specs/projects/<project>/INDEX.md (find your workstream)
2. Read the workstream SPEC.md (find your chunk)
3. If you need architecture context, read the project OVERVIEW.md
That's it. Do not read framework docs unless you are writing a new spec.
```
This replaces the current "Read README → framework docs → project overview → workstream overview → spec" path.
## Impact
| Metric | Before | After | Delta | How to measure |
| ------------------------------------ | ---------------------------------------------- | ------------------------------------- | -------- | ----------------------------------------------------- |
| Files an agent reads per chunk | 3-5 | 1-2 | -60% | Trace the reading path in CLAUDE.md planning protocol |
| Spec files in repo | 30 | ~15 | -50% | `find specs -name '*.md' \| wc -l` |
| Directory depth to a workstream SPEC | 5 (`specs/projects/sdk/workstreams/x/SPEC.md`) | 4 (`specs/sdk/workstreams/x/SPEC.md`) | -1 level | `find specs -name 'SPEC.md' -exec echo {} \;` |
| Total spec lines | 10,350 | ~7,500 | -27% | `find specs -name '*.md' -exec cat {} + \| wc -l` |
| Duplicated north star instances | 12 | 6 | -50% | `rg -c 'North Star' specs/ --glob '!archive/'` |
| Duplicated rules reminder instances | 10 | 1 (CLAUDE.md) | -90% | `rg -c 'Rules Reminder' specs/ --glob '!archive/'` |
| "Project" directories | 5 (sdk, kmp, lottie, euclid, ci) | 1 (sdk) | -80% | `ls specs/sdk` is the only project |
## Execution Plan
### Chunk 1: Consolidate framework into CLAUDE.md and AGENTS.md — S (~2k tokens)
1. Audit PROJECT-RULES.md — diff against CLAUDE.md, add missing rules
2. Audit SPEC-GUIDE.md — move "Writing for AI Agents" essentials to CLAUDE.md planning protocol
3. Add spec-reading protocol to CLAUDE.md
4. Update all AGENTS.md files (`app/AGENTS.md`, `packages/mobile-sdk-alpha/AGENTS.md`, `noir/AGENTS.md`) — remove any references to PROJECT-RULES.md or SPEC-GUIDE.md, ensure they point to CLAUDE.md for rules
5. Archive PROJECT-RULES.md and SPEC-GUIDE.md (move to `specs/archive/`)
6. Validate: grep for references to moved files, update links
### Chunk 2: Merge OVERVIEWs into SPECs — M (~5k tokens)
For each of the 5 workstreams:
1. Extract useful content from OVERVIEW.md (what you own, architecture context, dependencies)
2. Add as `## Context` section at top of SPEC.md (after north star)
3. Remove duplicated north star, rules reminder, spec deviations from SPEC.md
4. Delete OVERVIEW.md
5. Update INDEX.md workstream table
### Chunk 3: Flatten SDK project level — S (~2k tokens)
1. Merge PLAN.md chunk inventory into OVERVIEW.md status section
2. Merge HANDOFF.md open items into OVERVIEW.md. Archive resolved decisions.
3. Delete STATUS.md, PLAN.md, HANDOFF.md
4. Update INDEX.md
### Chunk 4: Strip ceremony from templates — S (~1k tokens)
1. Remove boilerplate sections from TEMPLATES.md
2. Update the template to match the new simplified structure
3. Keep PRODUCT-SPEC-ENHANCEMENT-PROMPT.md (it's a standalone tool, not spec ceremony)
### Chunk 5: Collapse fake projects and flatten hierarchy — M (~4k tokens)
1. `git mv specs/projects/sdk/ specs/sdk/`
2. Move standalone docs to `specs/topics/` with descriptive names:
- `specs/projects/lottie/REVIEW.md` → `specs/topics/LOTTIE-DOTLOTTIE-REVIEW.md`
- `specs/projects/euclid/PLAN.md` → `specs/topics/EUCLID-WEB-CONSOLIDATION.md`
- `specs/projects/ci/COVERAGE-GAPS.md` → `specs/topics/CI-COVERAGE-GAPS.md`
- `specs/shared/handoffs/SECURITY-HARDENING.md` → `specs/topics/SECURITY-HARDENING.md`
3. Archive KMP skeletons to `specs/archive/kmp/`
4. Delete empty directories: `specs/projects/`, `specs/shared/`, `specs/projects/lottie/`, `specs/projects/euclid/`, `specs/projects/ci/`, `specs/projects/kmp/`
5. Update `specs/README.md` to flat structure
6. Validate: `find specs/projects -type f 2>/dev/null` returns empty (directory gone)
### Chunk 6: Update all cross-references — S (~2k tokens)
1. Grep for all references to deleted/moved files across the entire repo (not just `specs/`)
2. Update links in CLAUDE.md, README.md, all AGENTS.md files (`app/AGENTS.md`, `packages/mobile-sdk-alpha/AGENTS.md`, `noir/AGENTS.md`), and remaining specs
3. Key path changes to grep for:
- `specs/projects/` → `specs/sdk/` or `specs/topics/`
- `specs/shared/` → `specs/topics/`
- `specs/projects/kmp/` → archived
- `specs/projects/lottie/` → `specs/topics/LOTTIE-DOTLOTTIE-REVIEW.md`
- `specs/projects/euclid/` → `specs/topics/EUCLID-WEB-CONSOLIDATION.md`
- `specs/projects/ci/` → `specs/topics/CI-COVERAGE-GAPS.md`
- Workstream `OVERVIEW.md` → deleted (merged into SPEC.md)
- `PROJECT-RULES.md`, `SPEC-GUIDE.md` → archived
- `PLAN.md`, `HANDOFF.md`, `STATUS.md` → merged into OVERVIEW.md
4. Validate with full legacy-path grep (must return zero hits outside `specs/archive/`):
```bash
# Must return empty (no stale references outside archive and this spec)
rg --glob '!specs/archive/**' --glob '!specs/projects/sdk/SPEC-AGENT-OPTIMIZATION.md' \
-n 'specs/shared/|PROJECT-RULES\.md|SPEC-GUIDE\.md|workstreams/[^/]+/OVERVIEW\.md|/sdk/PLAN\.md|/sdk/HANDOFF\.md|/sdk/STATUS\.md' \
specs/ CLAUDE.md app/AGENTS.md packages/*/AGENTS.md noir/AGENTS.md
# Verify no dead links — extract all relative markdown links and check they resolve
for f in $(find specs -name '*.md'); do
dir=$(dirname "$f")
grep -oP '\[.*?\]\(\K[^)#]+' "$f" 2>/dev/null | while read -r link; do
[[ "$link" =~ ^https?:// ]] && continue
target="$dir/$link"
[ ! -f "$target" ] && echo "BROKEN: $f -> $link"
done
done
```
## Dependency Graph
```
Chunk 1 (framework → CLAUDE.md + AGENTS.md)
'---> Chunk 4 (strip templates)
Chunk 2 (merge OVERVIEWs)
Chunk 3 (flatten SDK project level)
Chunk 5 (collapse fake projects) ← depends on chunk 3 (sdk/ paths must be stable first)
'---> Chunk 6 (update cross-refs, after 1-5)
```
Chunks 1, 2, 3 can run in parallel. Chunk 4 depends on 1. Chunk 5 depends on 3. Chunk 6 is cleanup after all others.
## Definition of Done
An agent can execute any SDK workstream chunk by reading at most 2 files (`specs/sdk/INDEX.md` + workstream `SPEC.md`), with no duplicated context across files, no process boilerplate in the spec, and no fake project directories to navigate through.
## Risks
| Risk | Mitigation |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Losing useful OVERVIEW context during merge | Extract before deleting — review the merged SPEC.md for completeness |
| CLAUDE.md getting too long | Keep rules concise — the file is already ~100 lines, adding ~30 lines of consolidated rules won't bloat it |
| Human spec authors lose guidance | TEMPLATES.md remains as the reference. Authors who need process guidance can read the archived SPEC-GUIDE. |
| Breaking existing agent workflows | Chunk 5 catches stale references across entire repo (including AGENTS.md files). The reading path gets simpler, not different. |
| KMP skeleton docs have future value | Archive them — if KMP becomes its own project later, skeletons can be restored. Real KMP execution is already in `sdk/workstreams/native-shells/SPEC.md` |
| Merging PLAN/HANDOFF loses active work tracking | Closure gate: all partial/deferred chunks have next-step descriptions, all P1 handoff items have owner+status before source files are deleted |
## What This Does NOT Change
- Workstream folder structure (`workstreams/<scope>/`) — stays as-is
- SPEC.md chunk format (goal, steps, I/O, validation) — stays as-is
- OVERVIEW.md at the SDK project level — stays (it's genuinely useful architecture context)
- TEMPLATES.md — stays (simplified but still the copy-paste reference)
- Archive system — stays
## Completion Status
| Chunk | Description | Size | Status |
| ----- | ------------------------------------------------ | ---- | -------- |
| 1 | Consolidate framework into CLAUDE.md + AGENTS.md | S | **Done** |
| 2 | Merge OVERVIEWs into SPECs | M | **Done** |
| 3 | Flatten SDK project level | S | **Done** |
| 4 | Strip ceremony from templates | S | **Done** |
| 5 | Collapse fake projects + flatten hierarchy | M | **Done** |
| 6 | Update all cross-references | S | **Done** |

68
specs/person3-integrations/SPEC-MINIPAY-SAMPLE.md → specs/projects/sdk/workstreams/integrations/SPEC.md
View File

@@ -1,9 +1,8 @@
# Person 3: MiniPay Integration Sample — Implementation Spec
> Last updated: 2026-03-02
> Last updated: 2026-03-05
> Owner: Person 3 (Integrations)
> Parent: [OVERVIEW.md](./OVERVIEW.md)
> Project: [SDK-OVERVIEW.md](../SDK-OVERVIEW.md)
> Project: [SDK Overview](../../OVERVIEW.md)
> Status: Active
## North Star
@@ -12,6 +11,49 @@
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Context
**What you own:**
- **MiniPay sample app** (`packages/kmp-minipay-sample/`) — Kotlin/Compose Multiplatform reference integration
- **Future integration samples** — Self Wallet migration sample, other third-party app examples
**Architecture context:**
```
┌────────────────────────────────────────┐
│ Sample App (Compose Multiplatform) │
│ HomeScreen ──→ SelfSdk.launch() ──→ ResultScreen
│ (native) (SDK WebView) (native)
└────────────────────┬───────────────────┘
│
┌───────────▼───────────┐
│ KMP SDK (kmp-sdk/) │
│ 5 native handlers │
│ WebView host │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ WebView (Vite bundle)│
│ Full verification │
│ flow: 10 screens │
└───────────────────────┘
```
**Dependencies:**
| Direction | Person / Package | What | Status |
| ------------ | ------------------ | ---------------------------------------------- | ------ |
| **You need** | Person 2 (KMP SDK) | `SelfSdk.launch()` API and Kotlin SDK artifact | Done |
| **You need** | Person 1 (WebView) | Vite bundle embedded in the SDK | Ready |
**Status:**
- [x] MiniPay sample project scaffolded
- [x] Android + iOS launch path wiring present
- [x] Error-code to user-message mapping in result UX
- [ ] Polish + error handling (chunk 3C — partial)
## Overview
You are building a Kotlin sample app demonstrating how a host app integrates Self identity verification using the KMP SDK's `SelfSdk.launch()` API. The app has a minimal native UI — a home screen with a "Verify Identity" button and a result screen. All verification logic (country selection, document scanning, NFC, proving, result) runs inside the SDK's WebView, launched via a single `SelfSdk.launch()` call. This sample serves as the reference implementation for third-party integrators.
@@ -20,9 +62,9 @@ You are building a Kotlin sample app demonstrating how a host app integrates Sel
- Familiarity with Compose Multiplatform and the KMP project structure (shared/android/ios source sets)
- Familiarity with the KMP SDK public API: `SelfSdk.configure()`, `SelfSdk.launch()`, `SelfSdkCallback`
- **Bridge protocol** = JSON messaging over `postMessage` between WebView and native handlers (10 domains, see [SDK-OVERVIEW.md](../SDK-OVERVIEW.md))
- **Bridge protocol** = JSON messaging over `postMessage` between WebView and native handlers (10 domains, see [SDK Overview](../../OVERVIEW.md))
- **5 native handlers** = NFC, Camera/MRZ, Biometrics, Keychain, Lifecycle — the only native code the SDK requires
- Read [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) for architecture context
- Read [SDK Overview](../../OVERVIEW.md) for architecture context
## The Problem
@@ -803,17 +845,17 @@ rg -n "\\bverified\\s*=|disclosedClaims" packages/kmp-minipay-sample/composeApp/
## Dependencies
- **[person2-native-shells/SPEC.md](../person2-native-shells/SPEC.md)** — KMP SDK with 5 native handlers (NFC, Camera, Biometrics, Keychain, Lifecycle) and WebView host
- **[person1-webview/SPEC.md](../person1-webview/SPEC.md)** — Bundled Vite app that runs inside the WebView (all verification screens + proving logic)
- **[native-shells/SPEC.md](../native-shells/SPEC.md)** — KMP SDK with 5 native handlers (NFC, Camera, Biometrics, Keychain, Lifecycle) and WebView host
- **[webview/SPEC.md](../webview/SPEC.md)** — Bundled Vite app that runs inside the WebView (all verification screens + proving logic)
## Related Specs
- **Parent:** [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) — Architecture overview and north star
- **Parent:** [SDK Overview](../../OVERVIEW.md) — Architecture overview and north star
- **Sibling specs:**
- [person2-native-shells/SPEC.md](../person2-native-shells/SPEC.md) — Kotlin/Swift native shell (Person 2)
- [person1-webview/SPEC.md](../person1-webview/SPEC.md) — WebView UI + bridge (Person 1)
- [person4-sdk-core/SPEC.md](../person4-sdk-core/SPEC.md) — SDK core adaptation (Person 4)
- [person5-rn-sdk/SPEC.md](../person5-rn-sdk/SPEC.md) — React Native SDK (Person 5)
- [native-shells/SPEC.md](../native-shells/SPEC.md) — Kotlin/Swift native shell (Person 2)
- [webview/SPEC.md](../webview/SPEC.md) — WebView UI + bridge (Person 1)
- [sdk-core/SPEC.md](../sdk-core/SPEC.md) — SDK core adaptation (Person 4)
- [rn-sdk/SPEC.md](../rn-sdk/SPEC.md) — React Native SDK (Person 5)
---
@@ -850,7 +892,7 @@ rg -n "\\bverified\\s*=|disclosedClaims" packages/kmp-minipay-sample/composeApp/
| Item | Discovered during | Suggested spec |
| ------------------------------------------- | ----------------- | ---------------------------- |
| Production publishing (AAR + XCFramework) | — | New spec: SPEC-PUBLISHING.md |
| Self Wallet migration to `SelfVerification` | — | person5-rn-sdk/SPEC.md |
| Self Wallet migration to `SelfVerification` | — | rn-sdk/SPEC.md |
## Spec Deviations

95
specs/person2-native-shells/SPEC.md → specs/projects/sdk/workstreams/native-shells/SPEC.md
View File

@@ -1,8 +1,8 @@
# Person 2: Native Shells (KMP SDK + Swift Providers) — Implementation Spec
> Last updated: 2026-02-19
> Last updated: 2026-03-05
> Owner: Person 2 (Native Shells)
> Parent: [OVERVIEW.md](./OVERVIEW.md)
> Project: [SDK Overview](../../OVERVIEW.md)
> Status: Active
## North Star
@@ -11,6 +11,65 @@
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Context
**What you own:**
- `packages/kmp-sdk/` — Kotlin Multiplatform SDK (Android + iOS targets)
- `packages/self-sdk-swift/` — Swift companion package for iOS providers
- Android native handlers (NFC, Camera, Biometrics, Keychain, Lifecycle)
- iOS native handlers (via Swift provider pattern — no cinterop)
- `SelfSdk.launch()` public API for host apps
**Architecture context:**
```
┌──────────────────────────────────────────────────┐
│ HOST APP │
│ (MiniPay / Self Wallet / etc.) │
└────────────────────┬─────────────────────────────┘
│
┌────────────────▼────────────────┐
│ YOUR LAYER (Person 2) │
│ ┌───────────┐ ┌────────────┐ │
│ │ Android │ │ iOS │ │
│ │ kmp-sdk │ │ kmp-sdk + │ │
│ │ (Kotlin) │ │ Swift pkg │ │
│ └─────┬─────┘ └──────┬─────┘ │
│ NFC · Camera · Biometrics │
│ Keychain · Lifecycle │
│ ┌─────▼───────────────▼─────┐ │
│ │ WebView Host │ │
│ │ (loads Person 1 bundle) │ │
│ └─────────────┬─────────────┘ │
└────────────────┼────────────────┘
│ JSON postMessage
┌────────────────▼────────────────┐
│ BRIDGE PROTOCOL (Person 1) │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ WEBVIEW UI (Person 1) │
└─────────────────────────────────┘
```
**Dependencies:**
| Direction | Person / Package | What | Status |
| ------------- | ---------------- | ------------------------------------------------- | ------ |
| **You need** | Person 1 | Vite bundle (`dist/`) loaded into your WebView | Ready |
| **You need** | Person 1 | Bridge protocol types (`@selfxyz/webview-bridge`) | Ready |
| **Needs you** | Person 5 | Bridge protocol as reference for RN handler | Ready |
| **Needs you** | Integrations | `SelfSdk.launch()` API consumed by MiniPay sample | Done |
**Status:**
- [x] Android: 5 handlers + WebView host + Activity
- [x] iOS: Swift providers wired (NFC, Biometrics, Lifecycle, WebView host)
- [x] Platform asymmetry contract documented and signed off
- [ ] SDK Public API finalize (chunk 2F — partial)
- [ ] Camera MRZ Handler iOS (chunk 2L — deferred Phase 2)
## Overview
You are building the native side of the Self Mobile SDK — the Kotlin Multiplatform module (`packages/kmp-sdk/`) and the Swift companion package (`packages/self-sdk-swift/`). This means hosting a WebView containing Person 1's Vite bundle, routing bridge messages from the WebView to native handlers, and providing `SelfSdk.launch()` as the public API for host apps. On Android, handlers are written directly in Kotlin. On iOS, handlers delegate to Swift provider implementations via a factory pattern (cinterop is abandoned). This matters because it is the only native code standing between third-party host apps and the verification flow — it must be thin, correct, and easy to integrate.
@@ -22,7 +81,7 @@ You are building the native side of the Self Mobile SDK — the Kotlin Multiplat
- **Bridge protocol** = versioned JSON over `postMessage` (10 domains, request/response/event)
- **Handler** = native-side implementation of a bridge domain (e.g., `NfcBridgeHandler`)
- **Provider** = Swift protocol implementation injected into KMP iOS handlers via factory pattern
- Read [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) for architecture context and the full decision matrix
- Read [SDK Overview](../../OVERVIEW.md) for architecture context and the full decision matrix
## The Problem
@@ -59,7 +118,7 @@ Delete four Android handlers -- the WebView handles their functionality using st
| **AnalyticsBridgeHandler** | 94 LOC | `console` / `fetch` | Analytics events logged via console or sent via fetch from the WebView; fire-and-forget |
| **HapticBridgeHandler** | 94 LOC | Skipped | Haptic feedback is not critical to verification flow; WebView skips it |
**Total savings:** 511 LOC deleted from Android, 6 fewer iOS handlers to build. See the Decision Matrix in [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) for the full architecture rationale.
**Total savings:** 511 LOC deleted from Android, 6 fewer iOS handlers to build. See the Decision Matrix in [SDK Overview](../../OVERVIEW.md) for the full architecture rationale.
> **Keychain note:** SecureStorage stays native because host apps (like MiniPay) control keychain access policy. The WebView must not have direct keychain access.
@@ -2101,7 +2160,7 @@ cd packages/self-sdk-swift && swift build
- **Person 4 (SDK Core):** They own the adapter interfaces in `packages/mobile-sdk-alpha/src/types/public.ts`. The WebView engine calls your native handlers through these adapters. If adapter signatures change, the bridge protocol may need updating.
- **Person 5 (RN Native Shell):** They build a separate native shell (`packages/rn-sdk/`) using the same bridge protocol. Share handler method contracts and test vectors. Their `SelfVerification` component loads the same Vite bundle you do.
- **PR #1762:** iOS bridge handlers with Swift provider pattern added `self-sdk-swift` and unblocked the 2G-2K implementation path.
- **MiniPay Integration:** The [SPEC-MINIPAY-SAMPLE.md](../person3-integrations/SPEC-MINIPAY-SAMPLE.md) depends on this spec for iOS SDK functionality. Android side is already working.
- **MiniPay Integration:** The [SPEC.md](../integrations/SPEC.md) depends on this spec for iOS SDK functionality. Android side is already working.
## Key Reference Files
@@ -2121,13 +2180,13 @@ cd packages/self-sdk-swift && swift build
## Related Specs
| Spec | Relationship |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Parent architecture spec -- north star, decision matrix, shared contracts |
| [person1-webview/SPEC.md](../person1-webview/SPEC.md) | Sibling -- owns WebView UI, bridge adapters, Vite bundle you consume |
| [person4-sdk-core/SPEC.md](../person4-sdk-core/SPEC.md) | Sibling -- owns SDK core, adapter interfaces your handlers implement |
| [person5-rn-sdk/SPEC.md](../person5-rn-sdk/SPEC.md) | Sibling -- separate native shell using same bridge protocol |
| [person3-integrations/SPEC-MINIPAY-SAMPLE.md](../person3-integrations/SPEC-MINIPAY-SAMPLE.md) | Downstream -- MiniPay sample app depends on this SDK |
| Spec | Relationship |
| ----------------------------------------------- | ------------------------------------------------------------------------- |
| [SDK Overview](../../OVERVIEW.md) | Parent architecture spec -- north star, decision matrix, shared contracts |
| [webview/SPEC.md](../webview/SPEC.md) | Sibling -- owns WebView UI, bridge adapters, Vite bundle you consume |
| [sdk-core/SPEC.md](../sdk-core/SPEC.md) | Sibling -- owns SDK core, adapter interfaces your handlers implement |
| [rn-sdk/SPEC.md](../rn-sdk/SPEC.md) | Sibling -- separate native shell using same bridge protocol |
| [integrations/SPEC.md](../integrations/SPEC.md) | Downstream -- MiniPay sample app depends on this SDK |
---
@@ -2161,12 +2220,12 @@ cd packages/self-sdk-swift && swift build
## Follow-Up (Out of Scope)
| Item | Discovered during | Suggested spec |
| -------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Camera MRZ handler for iOS | Chunk 2L scoping | Phase 2 -- add to this spec when needed |
| SecureStorage handler for iOS | Design review | **Decided:** Add `SecureStorageProvider` to factory pattern (see SDK-OVERVIEW canonical rule) |
| Crypto signing handler for iOS | Design review | Depends on whether secure enclave signing is needed vs. Web Crypto |
| LifecycleBridgeHandler thin-wrapper refactor | PR #1805 review | Both Android and iOS `setResult()` have 4-branch business logic (interpreting `type`/`success`/`errorCode` to decide result codes / callback methods). Per PROJECT-RULES.md rule 22 ("no error mapping in native"), TypeScript should send an explicit `resultCode` or `outcome` field, and the handler should pass it through without interpretation. Touches both platform handlers + bridge protocol. |
| Item | Discovered during | Suggested spec |
| -------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Camera MRZ handler for iOS | Chunk 2L scoping | Phase 2 -- add to this spec when needed |
| SecureStorage handler for iOS | Design review | **Decided:** Add `SecureStorageProvider` to factory pattern (see SDK-OVERVIEW canonical rule) |
| Crypto signing handler for iOS | Design review | Depends on whether secure enclave signing is needed vs. Web Crypto |
| LifecycleBridgeHandler thin-wrapper refactor | PR #1805 review | Both Android and iOS `setResult()` have 4-branch business logic (interpreting `type`/`success`/`errorCode` to decide result codes / callback methods). Per CLAUDE.md rule ("Native handlers are thin wrappers — no error mapping in native"), TypeScript should send an explicit `resultCode` or `outcome` field, and the handler should pass it through without interpretation. Touches both platform handlers + bridge protocol. |
## Spec Deviations

71
specs/person5-rn-sdk/SPEC.md → specs/projects/sdk/workstreams/rn-sdk/SPEC.md
View File

@@ -1,8 +1,8 @@
# RN Native Shell — Implementation Spec
> Last updated: 2026-03-02
> Last updated: 2026-03-05
> Owner: Person 5 (RN SDK)
> Parent: [OVERVIEW.md](./OVERVIEW.md)
> Project: [SDK Overview](../../OVERVIEW.md)
> Status: Active
## North Star
@@ -11,6 +11,57 @@
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Context
**What you own:**
- **`@selfxyz/rn-sdk`** — the React Native SDK package
- **`SelfVerification`** component (~200-300 LOC) — the single public API surface
- **5 native handler bridges** — NFC, Camera, Biometrics, Keychain, Lifecycle (thin wrappers around RN native modules)
- **Asset bundling** — Vite bundle loaded into `react-native-webview` on iOS + Android
**Architecture context:**
```
┌─────────────────────────────────────────┐
│ HOST APP (React Native) │
│ <SelfVerification │
│ userId="..." onComplete={...} │
│ /> │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ ★ YOUR LAYER: @selfxyz/rn-sdk │
│ SelfVerification.tsx │
│ └─ react-native-webview │
│ MessageRouter.ts │
│ ├─ NfcHandler · CameraHandler │
│ ├─ BiometricsHandler · KeychainHandler│
│ └─ LifecycleHandler │
└──────────────┬──────────────────────────┘
│ postMessage (JSON) — same protocol as KMP
┌──────────────▼──────────────────────────┐
│ SHARED WEBVIEW (Person 1 + 4) │
│ Vite bundle: webview-app + engine │
└─────────────────────────────────────────┘
```
**Dependencies:**
| Direction | Person / Package | What | Status |
| ------------- | --------------------------- | -------------------------------------------------- | ----------- |
| **You need** | Person 1 (`webview-app`) | Vite bundle (`dist/`) | Ready |
| **You need** | Person 1 (`webview-bridge`) | Bridge protocol types | Ready |
| **Needs you** | Self Wallet app | `SelfVerification` for verification flow (Phase 2) | Not started |
**Status:**
- [x] Package scaffolded with `SelfVerification` component
- [x] All 5 native handler bridges implemented (including APDU-capable NFC)
- [x] Asset loading for iOS + Android implemented
- [ ] Integration validation in Self Wallet app (follow-up)
- [ ] npm publish not completed
## Overview
You are building the **React Native native shell** (`@selfxyz/rn-sdk`) — a thin `SelfVerification` component that wraps `react-native-webview` to embed the Self verification flow inside any React Native app. It shares the same WebView engine, bridge protocol, and UI as the Kotlin native shell. The only RN-specific code is ~200-300 LOC of native handler bridges and the component wrapper. This matters because React Native hosts (Self Wallet, third-party apps) need the same verification flow that Kotlin hosts (MiniPay) get, without duplicating any logic.
@@ -21,7 +72,7 @@ You are building the **React Native native shell** (`@selfxyz/rn-sdk`) — a thi
- Familiarity with the bridge protocol defined in `@selfxyz/webview-bridge` (JSON `request`/`response`/`event` over `postMessage`)
- `Handler` = a native-side class that implements one bridge domain (e.g., `NfcHandler` handles the `nfc` domain)
- `MessageRouter` = JS-side dispatcher that routes incoming WebView messages to the correct handler by domain
- Read [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) for architecture context
- Read [SDK Overview](../../OVERVIEW.md) for architecture context
## The Problem
@@ -1112,7 +1163,7 @@ ls packages/rn-sdk/assets/self-wallet/index.html # Assets bundled
| Item | Discovered during | Suggested spec |
| -------------------------------------------- | ----------------- | ----------------------------------------------------------------- |
| Self Wallet migration to `SelfVerification` | Spec writing | Separate migration spec after SDK is stable |
| MiniPay RN sample integration | Spec writing | `SPEC-MINIPAY-SAMPLE.md` (already exists) |
| MiniPay RN sample integration | Spec writing | `integrations/SPEC.md` (already exists) |
| Camera library selection for MRZ scanning | Chunk 5C planning | Depends on host app camera setup -- may need configurable adapter |
| iOS asset loading strategy (RNFS vs require) | PR #1765 review | **Decided:** Use RN `require()` + Metro `html` asset support |
@@ -1136,9 +1187,9 @@ ls packages/rn-sdk/assets/self-wallet/index.html # Assets bundled
## Related Specs
| Spec | Relationship |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Parent architecture spec |
| [person1-webview/SPEC.md](../person1-webview/SPEC.md) | Builds the WebView UI + bridge that this SDK loads |
| [person2-native-shells/SPEC.md](../person2-native-shells/SPEC.md) | Kotlin native shell -- same bridge protocol, reference handlers |
| [person4-sdk-core/SPEC.md](../person4-sdk-core/SPEC.md) | SDK core adaptation -- Chunk 4F (web fallback adapters) is a prerequisite |
| Spec | Relationship |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| [SDK Overview](../../OVERVIEW.md) | Parent architecture spec |
| [webview/SPEC.md](../webview/SPEC.md) | Builds the WebView UI + bridge that this SDK loads |
| [native-shells/SPEC.md](../native-shells/SPEC.md) | Kotlin native shell -- same bridge protocol, reference handlers |
| [sdk-core/SPEC.md](../sdk-core/SPEC.md) | SDK core adaptation -- Chunk 4F (web fallback adapters) is a prerequisite |

70
specs/person4-sdk-core/SPEC.md → specs/projects/sdk/workstreams/sdk-core/SPEC.md
View File

@@ -1,8 +1,8 @@
# Person 4: SDK Core Adaptation — Implementation Spec
> Last updated: 2026-03-02
> Last updated: 2026-03-05
> Owner: Person 4 (SDK Core)
> Parent: [OVERVIEW.md](./OVERVIEW.md)
> Project: [SDK Overview](../../OVERVIEW.md)
> Status: Active
## North Star
@@ -11,6 +11,56 @@
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Context
**What you own:**
- **`@selfxyz/mobile-sdk-alpha`** — the WebView engine (proving machine, stores, adapters, document management)
- **Browser entry point** (`src/browser.ts`) — the import path for WebView consumers, with zero `react-native` transitive imports
- **Web fallback adapter implementations** — IndexedDB for documents, Web Crypto for hashing, console/fetch for analytics
- **Platform abstraction** for adapter interfaces — making the engine portable across RN and browser/WebView contexts
**Architecture context:**
```
┌──────────────────────────────────────┐
│ Person 1: WebView UI │
│ (webview-app, screens, router) │
│ Consumes: useSelfClient(), stores, │
│ proving machine, adapter interfaces │
└──────────────────┬───────────────────┘
│
╔══════════════╧═══════════════╗
║ Person 4: SDK Engine (YOU) ║
║ (mobile-sdk-alpha) ║
║ Proving machine (XState) ║
║ Document store (Zustand) ║
║ Adapter interfaces ║
║ Two entry points: ║
║ ├─ src/index.ts (RN) ║
║ └─ src/browser.ts (WebView) ║
╚══════════════╤═══════════════╝
│
┌──────────────┴───────────────┐
│ Shared Utilities │
│ (common/) │
└──────────────────────────────┘
```
**Dependencies:**
| Direction | Person / Package | What | Status |
| ------------- | ---------------- | --------------------------------------------------------------------------- | ------ |
| **You need** | Nobody | Independent in Phase 1 | Ready |
| **Needs you** | Person 1 | Adapter interfaces, core logic (`useSelfClient()`, stores, proving machine) | Active |
| **Needs you** | Person 5 | Browser entry point working in RN WebView context | Done |
**Status:**
- [x] All chunks done (4A–4F) — config, browser entry, lifecycle events, conditional store, web fallbacks
- [ ] Bridge-layer fallback duplicates not yet fully removed
- [ ] `generateKey()`/`getPublicKey()` not exposed in `BridgeCryptoAdapter` interface
## Overview
You are making **`@selfxyz/mobile-sdk-alpha`** work cleanly inside a browser/WebView context. This package is the "WebView engine" — it contains all core logic (proving machine, stores, document management, protocol state) that Person 1's screen components consume via `useSelfClient()`.
@@ -28,7 +78,7 @@ You are NOT building screens or native handlers. You are making the engine porta
- Familiarity with Zustand (state management for stores)
- `Adapters` = the adapter interfaces in `src/types/public.ts` that decouple core logic from platform APIs
- `Browser entry point` = `src/browser.ts`, the import path used by WebView consumers (must have zero `react-native` imports)
- Read [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) for architecture context
- Read [SDK Overview](../../OVERVIEW.md) for architecture context
## The Problem
@@ -732,13 +782,13 @@ grep -r "NativeModules\|NativeEventEmitter\|requireNativeComponent" packages/web
## Related Specs
| Spec | Relationship |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | Parent architecture spec |
| [person1-webview/SPEC.md](../person1-webview/SPEC.md) | Sibling — builds WebView UI that consumes your adapter interfaces and browser entry point |
| [person2-native-shells/SPEC.md](../person2-native-shells/SPEC.md) | Sibling — builds native handlers that implement bridge protocol, consumes your lifecycle types |
| [person5-rn-sdk/SPEC.md](../person5-rn-sdk/SPEC.md) | Sibling — RN native shell that uses your browser entry point |
| [person3-integrations/SPEC-MINIPAY-SAMPLE.md](../person3-integrations/SPEC-MINIPAY-SAMPLE.md) | Downstream — MiniPay sample depends on SDK core through KMP SDK |
| Spec | Relationship |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [SDK Overview](../../OVERVIEW.md) | Parent architecture spec |
| [webview/SPEC.md](../webview/SPEC.md) | Sibling — builds WebView UI that consumes your adapter interfaces and browser entry point |
| [native-shells/SPEC.md](../native-shells/SPEC.md) | Sibling — builds native handlers that implement bridge protocol, consumes your lifecycle types |
| [rn-sdk/SPEC.md](../rn-sdk/SPEC.md) | Sibling — RN native shell that uses your browser entry point |
| [integrations/SPEC.md](../integrations/SPEC.md) | Downstream — MiniPay sample depends on SDK core through KMP SDK |
---

74
specs/person1-webview/SPEC.md → specs/projects/sdk/workstreams/webview/SPEC.md
View File

@@ -1,8 +1,8 @@
# Person 1: WebView UI + Bridge — Implementation Spec
> Last updated: 2026-02-17
> Last updated: 2026-03-05
> Owner: Person 1 (WebView UI + Bridge)
> Parent: [OVERVIEW.md](./OVERVIEW.md)
> Project: [SDK Overview](../../OVERVIEW.md)
> Status: Active
## North Star
@@ -11,6 +11,58 @@
- **Success metric:** A host app calls `SelfSdk.launch(request)`, gets back a verified proof, and the entire flow runs inside a shared WebView.
- **Constraint:** NFC, camera, biometrics, and keychain are the ONLY things that touch native code. Everything else runs in the WebView.
## Context
**What you own:**
- **`@selfxyz/webview-bridge`** — Bridge protocol library (public npm). Pure TypeScript, no react-native imports.
- **`@selfxyz/webview-app`** — Vite-bundled React app (bundled into native SDKs). 10 screens, Tamagui UI, React Router, BridgeProvider, SelfClientProvider.
- **Web fallback adapters** — IndexedDB for documents, Web Crypto for hashing, console/fetch for analytics, React Router for navigation, no-op for haptic.
**Architecture context:**
```
┌──────────────────────────────────────────────────┐
│ NATIVE SHELLS (Person 2 / 5) │
│ KMP (Android + iOS) | RN (react-native-webview)│
│ 5 native handlers: NFC, Camera, Bio, Key, Life │
└──────────────────────┬───────────────────────────┘
│ postMessage (JSON)
┌─────────────▼──────────────┐
│ @selfxyz/webview-bridge │ ◄── YOU BUILD THIS
│ Bridge protocol + adapters │
└─────────────┬──────────────┘
│
┌─────────────▼──────────────┐
│ @selfxyz/webview-app │ ◄── YOU BUILD THIS
│ 10 screens, providers, │
│ Vite bundle (dist/) │
└─────────────┬──────────────┘
│ imports adapters + hooks
┌─────────────▼──────────────┐
│ @selfxyz/mobile-sdk-alpha │ (Person 4)
│ Proving machine, stores, │
│ adapter interfaces │
└────────────────────────────┘
```
**Dependencies:**
| Direction | Person / Package | What | Status |
| ------------- | ----------------------------- | ---------------------------------------------------------------- | ------ |
| **You need** | Person 4 (`mobile-sdk-alpha`) | Adapter interfaces, `useSelfClient()` hook, color/font constants | Active |
| **You need** | Person 2 (KMP / Swift shells) | Native handler implementations on the other side of the bridge | Done |
| **Needs you** | Person 2 (KMP / Swift shells) | Vite bundle (`dist/index.html` + JS) embedded into native SDK | Ready |
| **Needs you** | Person 5 (RN SDK) | Same Vite bundle loaded via `react-native-webview` | Ready |
**Status:**
- [x] Bridge protocol types and `WebViewBridge` class (63 tests pass)
- [x] All 10 screens built and routing works
- [x] Biometrics + camera bridge adapters wired in `SelfClientProvider`
- [x] Hybrid crypto contract signed off
- [ ] Dynamic proof request items are still hardcoded in `ProvingScreen`
## Overview
You are building the **web side** of the Self Mobile SDK: the bridge protocol library (`@selfxyz/webview-bridge`) and the Vite-bundled React app (`@selfxyz/webview-app`) that runs inside a native WebView. This matters because every screen, adapter wire-up, and bridge message you implement becomes the single shared UI that ships to every host app — Kotlin, React Native, or otherwise. The output of `vite build` (a single `index.html` + JS bundle) gets bundled into the native SDK artifact.
@@ -20,9 +72,9 @@ You are building the **web side** of the Self Mobile SDK: the bridge protocol li
- Familiarity with **Vite** (build tool, `vite.config.ts`, dev server, production builds)
- Familiarity with **Tamagui** (cross-platform UI kit, `createTamagui`, font config, `YStack`/`XStack`/`Text`/`View`)
- Familiarity with **React Router** (`BrowserRouter`, `Routes`, `Route`, `useNavigate`)
- Familiarity with the **bridge protocol** (JSON over `postMessage`, request/response/event lifecycle) — see [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) "Shared Contracts / Protocols"
- Familiarity with the **bridge protocol** (JSON over `postMessage`, request/response/event lifecycle) — see [SDK Overview](../../OVERVIEW.md) "Shared Contracts / Protocols"
- **Adapter interfaces** are defined in `packages/mobile-sdk-alpha/src/types/public.ts` — read that file before implementing any adapter
- Read [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) for architecture context
- Read [SDK Overview](../../OVERVIEW.md) for architecture context
## The Problem
@@ -65,7 +117,7 @@ This spec covers **two packages**:
**`packages/webview-bridge/src/types.ts`**
All protocol types for the bridge messaging layer. These are the canonical TypeScript definitions matching the JSON protocol in [SDK-OVERVIEW.md](../SDK-OVERVIEW.md).
All protocol types for the bridge messaging layer. These are the canonical TypeScript definitions matching the JSON protocol in [SDK Overview](../../OVERVIEW.md).
```typescript
// SKELETON
@@ -1386,12 +1438,12 @@ ls packages/webview-app/dist/index.html # file must exist
## Related Specs
| Spec | Audience | What it covers |
| ----------------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| [SDK-OVERVIEW.md](../SDK-OVERVIEW.md) | All | Architecture, bridge protocol, domain catalog, dependency graph |
| [person2-native-shells/SPEC.md](../person2-native-shells/SPEC.md) | Person 2 | Kotlin/Swift native shells, Android/iOS handlers |
| [person4-sdk-core/SPEC.md](../person4-sdk-core/SPEC.md) | Person 4 | SDK core adaptation, RN dep removal, web fallbacks |
| [person5-rn-sdk/SPEC.md](../person5-rn-sdk/SPEC.md) | Person 5 | RN native shell, `SelfVerification` component |
| Spec | Audience | What it covers |
| ------------------------------------------------- | -------- | --------------------------------------------------------------- |
| [SDK Overview](../../OVERVIEW.md) | All | Architecture, bridge protocol, domain catalog, dependency graph |
| [native-shells/SPEC.md](../native-shells/SPEC.md) | Person 2 | Kotlin/Swift native shells, Android/iOS handlers |
| [sdk-core/SPEC.md](../sdk-core/SPEC.md) | Person 4 | SDK core adaptation, RN dep removal, web fallbacks |
| [rn-sdk/SPEC.md](../rn-sdk/SPEC.md) | Person 5 | RN native shell, `SelfVerification` component |
---

308
specs/topics/CI-COVERAGE-GAPS.md Normal file
View File

@@ -0,0 +1,308 @@
# CI Coverage Gaps — Packages
> Last updated: 2026-03-05
> Owner: SDK/infra maintainers
> Status: Active
## North Star
- Every package under `packages/` has CI that catches compilation, type, and test failures before merge
- No silent regressions on either platform (Android + iOS) for KMP packages
- New packages get CI as part of their creation — this spec closes the existing debt
## Status Checklist
- [ ] Chunk 1: webview-bridge CI
- [ ] Chunk 2: webview-app CI
- [ ] Chunk 3: KMP SDK — Android assemble + iOS framework link
- [ ] Chunk 4: KMP test app — Android assemble + iOS build
- [ ] Chunk 5: KMP minipay sample — Android assemble + iOS build
- [ ] Chunk 6: RN SDK test app — iOS build
- [ ] Chunk 7: self-sdk-swift — Swift build gate
## Current Coverage Audit
| Package | Dedicated CI | Tests | Types | Build | Android | iOS |
| -------------------- | ---------------------- | ------------- | ----- | ----- | ------------- | --- |
| `kmp-sdk` | kmp-ci.yml | jvmTest | — | — | — | — |
| `kmp-test-app` | kmp-ci.yml | debugUnitTest | — | — | — | — |
| `kmp-minipay-sample` | — | — | — | — | — | — |
| `mobile-sdk-alpha` | mobile-sdk-ci.yml | yes | yes | yes | — | — |
| `mobile-sdk-demo` | mobile-sdk-demo-ci.yml | yes | — | yes | — | — |
| `rn-sdk` | rn-sdk-test-app-ci.yml | yes | yes | tsup | — | — |
| `rn-sdk-test-app` | rn-sdk-test-app-ci.yml | — | yes | — | assembleDebug | — |
| `self-sdk-swift` | — | — | — | — | — | — |
| `webview-app` | — | — | — | — | n/a | n/a |
| `webview-bridge` | — | — | — | — | n/a | n/a |
Legend: "—" = missing, "n/a" = not applicable (JS-only package).
## Runner Reference
- Ubuntu: `ubuntu-latest`
- macOS (Apple Silicon): `namespace-profile-apple-silicon-6cpu`
## Overlap / Cleanup Opportunities
### 1. `mobile-ci.yml` build-ios and build-android are dead weight on PRs
Both jobs have `if: github.event_name == 'workflow_dispatch'` — they never run on PRs. The comments say "mostly covered in mobile-e2e.yml." But `mobile-e2e.yml` also only runs on `push` to protected branches + `workflow_dispatch` for the iOS job. Net result: **no iOS or Android build gate runs on PRs for `app/`** unless manually triggered. The `mobile-ci.yml` iOS/Android jobs should either be enabled on PRs or removed to reduce confusion.
**Recommendation:** Either remove the dead `build-ios`/`build-android` jobs from `mobile-ci.yml` (since `mobile-e2e.yml` covers them on push), or re-enable them on PRs if you want PR-level build gates. Don't keep both workflows with disabled jobs.
### 2. `mobile-sdk-demo-e2e.yml` Android E2E is build-only with all E2E steps `if: false`
Every Maestro/emulator step is guarded by `if: false`. It's a 170-line workflow that does `assembleDebug` + verify APK exists. The `mobile-sdk-demo-ci.yml` already does `test + build` for the demo app. The only unique value is the APK artifact verification — marginal.
**Recommendation:** Either re-enable the E2E tests or consolidate the Android build into `mobile-sdk-demo-ci.yml` and remove the dead workflow. The iOS E2E job in this workflow is actually live and useful — keep that.
### 3. `mobile-ci.yml` has debug logging that should be cleaned up
Steps like "Debug Cache Restoration", "Force Build Dependencies If Missing", and comments like "Temporarily always build to debug CI issues" suggest this workflow has accumulated debugging scaffolding that was never removed.
**Recommendation:** Clean up after the current caching issues are resolved. Not blocking but adds noise.
### 4. `mobile-sdk-ci.yml` duplicates build step across every job
Each of `lint`, `format`, `types`, `test` independently restores cache and falls back to a full rebuild. The `build` job saves the cache, but the restore is flaky enough that every job has a fallback build. This means `mobile-sdk-alpha` could be built up to 5 times in one CI run.
**Recommendation:** Low priority, but could use a shared artifact (upload/download) instead of cache if cache misses are frequent.
## Chunks
### Chunk 1: webview-bridge CI (S ~2k)
**Priority:** High — webview-bridge is a core dependency for rn-sdk and kmp-sdk.
**Create:** `.github/workflows/webview-bridge-ci.yml`
**Trigger paths:** `packages/webview-bridge/**`
**Jobs:**
- `build`: `yarn workspace @selfxyz/webview-bridge build`
- `types`: `yarn workspace @selfxyz/webview-bridge typecheck`
- `test`: `yarn workspace @selfxyz/webview-bridge test`
**Runner:** `ubuntu-latest`
**Files modified:**
- `.github/workflows/webview-bridge-ci.yml` (create)
**Files NOT modified:**
- `packages/webview-bridge/` (no source changes)
**Validation:**
```bash
# Trigger: open a PR that touches packages/webview-bridge
# Expect: workflow runs build, types, test jobs
gh workflow view webview-bridge-ci.yml
```
---
### Chunk 2: webview-app CI (S ~2k)
**Priority:** High — webview-app is the UI surface loaded by both KMP and RN SDKs. Zero CI today.
**Create:** `.github/workflows/webview-app-ci.yml`
**Trigger paths:** `packages/webview-app/**`, `packages/webview-bridge/**` (transitive dep)
**Jobs:**
- `build`: build webview-bridge first, then `yarn workspace @selfxyz/webview-app build`
- `types`: `yarn workspace @selfxyz/webview-app typecheck`
**Runner:** `ubuntu-latest`
**Files modified:**
- `.github/workflows/webview-app-ci.yml` (create)
**Files NOT modified:**
- `packages/webview-app/` (no source changes)
**Validation:**
```bash
gh workflow view webview-app-ci.yml
```
---
### Chunk 3: KMP SDK — Android assemble + iOS framework link (S ~2k)
**Priority:** High — iOS compilation is completely unchecked. Android compilation only happens transitively via jvmTest.
**Modify:** `.github/workflows/kmp-ci.yml`
**Add jobs:**
1. `android-build` (ubuntu-latest):
- `./gradlew :shared:assembleDebug`
2. `ios-framework` (namespace-profile-apple-silicon-6cpu):
- `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`
- Validates Kotlin/Native iOS compilation
3. `ios-test` (namespace-profile-apple-silicon-6cpu):
- `./gradlew :shared:iosSimulatorArm64Test`
- Runs common tests on iOS target
**Files modified:**
- `.github/workflows/kmp-ci.yml`
**Files NOT modified:**
- `packages/kmp-sdk/` (no source changes)
**Validation:**
```bash
# Local verification before pushing:
cd packages/kmp-sdk && ./gradlew :shared:assembleDebug
cd packages/kmp-sdk && ./gradlew :shared:linkDebugFrameworkIosSimulatorArm64
```
---
### Chunk 4: KMP test app — Android assemble + iOS build (M ~4k)
**Priority:** Medium — catches manifest/resource issues and iOS project breakage.
**Modify:** `.github/workflows/kmp-ci.yml`
**Add jobs:**
1. `kmp-test-app-android-build` (ubuntu-latest):
- `./gradlew :composeApp:assembleDebug`
2. `kmp-test-app-ios-build` (namespace-profile-apple-silicon-6cpu):
- Build the KMP framework first: `cd ../kmp-sdk && ./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`
- `cd packages/kmp-test-app/iosApp && pod install`
- `xcodebuild -workspace iosApp.xcworkspace -scheme iosApp -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 16' build`
**Trigger paths update:** Add `packages/kmp-test-app/**` (already present) and `packages/kmp-sdk/**` (already present).
**Files modified:**
- `.github/workflows/kmp-ci.yml`
**Files NOT modified:**
- `packages/kmp-test-app/` (no source changes)
**Validation:**
```bash
cd packages/kmp-test-app && ./gradlew :composeApp:assembleDebug
```
---
### Chunk 5: KMP minipay sample — Android assemble + iOS build (S ~2k)
**Priority:** Low — sample app, but should still compile.
**Modify:** `.github/workflows/kmp-ci.yml`
**Trigger paths update:** Add `packages/kmp-minipay-sample/**`
**Add jobs:**
1. `kmp-minipay-android-build` (ubuntu-latest):
- `cd packages/kmp-minipay-sample && ./gradlew :composeApp:assembleDebug`
2. `kmp-minipay-ios-build` (namespace-profile-apple-silicon-6cpu):
- Build KMP framework, pod install, xcodebuild (same pattern as chunk 4)
**Files modified:**
- `.github/workflows/kmp-ci.yml`
**Files NOT modified:**
- `packages/kmp-minipay-sample/` (no source changes)
---
### Chunk 6: RN SDK test app — iOS build (S ~3k)
**Priority:** Medium — Android build exists, iOS build is missing.
**Modify:** `.github/workflows/rn-sdk-test-app-ci.yml`
**Add job:**
1. `ios-build` (namespace-profile-apple-silicon-6cpu):
- `yarn install`
- Build webview-bridge (transitive dep)
- `cd packages/rn-sdk-test-app/ios && pod install`
- `xcodebuild -workspace RnSdkTestApp.xcworkspace -scheme RnSdkTestApp -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 16' build`
**Files modified:**
- `.github/workflows/rn-sdk-test-app-ci.yml`
**Files NOT modified:**
- `packages/rn-sdk-test-app/` (no source changes)
**Validation:**
```bash
cd packages/rn-sdk-test-app/ios && pod install && xcodebuild -workspace RnSdkTestApp.xcworkspace -scheme RnSdkTestApp -sdk iphonesimulator build
```
---
### Chunk 7: self-sdk-swift — Swift build gate (S ~2k)
**Priority:** Low — SPM package, should at least compile.
**Create:** `.github/workflows/swift-sdk-ci.yml`
**Trigger paths:** `packages/self-sdk-swift/**`
**Jobs:**
1. `build` (namespace-profile-apple-silicon-6cpu):
- `cd packages/self-sdk-swift && swift build`
**Files modified:**
- `.github/workflows/swift-sdk-ci.yml` (create)
**Files NOT modified:**
- `packages/self-sdk-swift/` (no source changes)
---
## Dependency Graph
```
Chunk 1 (webview-bridge) ──→ Chunk 2 (webview-app) depends on bridge CI existing
Chunk 3 (kmp-sdk) ──→ Chunk 4 (kmp-test-app) depends on kmp-sdk iOS framework
──→ Chunk 5 (kmp-minipay) same dependency
Chunk 6 (rn-sdk-test-app iOS) — independent
Chunk 7 (self-sdk-swift) — independent
```
Parallel execution: Chunks 1, 3, 6, 7 can all start in parallel. Chunk 2 after 1. Chunks 4, 5 after 3.
## Files NOT Modified
- No source code in any package is changed
- No test files are changed
- Only `.github/workflows/*.yml` files are created or modified
## Definition of Done
Every package under `packages/` triggers at least one CI workflow on PR that validates compilation succeeds on all platforms the package targets. The coverage audit table above has no "—" entries for applicable cells.

88
specs/topics/EUCLID-WEB-CONSOLIDATION.md Normal file
View File

@@ -0,0 +1,88 @@
# Euclid Web Consolidation Plan (Draft)
## Status
Draft and evolving. This document captures the current direction and will be refined as migration work progresses.
## Goal
Use `euclid-web` as the single source of truth for new SDK flow screens and business flow logic, while KMP/RN/mobile hosts become thin wrappers around a shared WebView flow.
## Target Architecture
1. `euclid-web` owns screen UI and flow orchestration.
2. Host apps (KMP demo, RN demo, mobile app) own only:
- WebView hosting
- bridge wiring
- platform permissions/lifecycle
- callback handoff to native caller
3. SDK surface remains stable while underlying UI/flow logic converges to web.
## Scope Boundary (Current)
In scope now:
- WebView launch reliability
- Host-to-web bridge contract
- Callback plumbing and smoke verification
Out of scope now:
- Full verification journey implementation parity in all hosts
- Consolidating/removing demo apps
- Reworking non-bridge native UI beyond what is needed for hosting
## Phased Plan
### Phase 0: Stabilize Launch (Current PR)
- Keep changes limited to launch reliability and local dev host setup.
- Ensure `kmp:start` reliably starts the web server and supports emulator/device access.
- Keep debug-only code removed unless required for ongoing validation.
### Phase 1: Shared Host Contract (Next PR)
- Define one shared config contract for URL/env/flags consumed by KMP + RN hosts.
- Define one shared event/callback contract (`success`, `error`, `cancel`, optional progress).
- Add smoke tests in each host for launch -> callback -> close path.
### Phase 2: Incremental Screen Migration
- All new flow screens land in `euclid-web` first.
- Remove duplicate native screens from demo apps as each flow area reaches parity.
- Keep demos as thin bridge/host harnesses during migration.
### Phase 3: Consolidate Demo Surface
- Decide final demo strategy once parity is high:
- single primary demo + one bridge harness, or
- both retained with explicit ownership and minimal overlap.
- De-scope duplicated flow logic from host apps.
### Phase 4: Mobile App Convergence
- Mobile app consumes the same `euclid-web` flow path as SDK demos.
- Native app keeps only host/platform concerns and app-specific shell concerns.
## Decision Rules
- If a change is launch/config/bridge related: belongs in host SDK work.
- If a change is flow UI/logic: belongs in `euclid-web`.
- If work duplicates flow code across hosts: treat as temporary and track removal.
## Open Questions
1. What is the long-term canonical demo app for partner validation?
2. What is the minimum bridge API required before flow migration accelerates?
3. Do we need a compatibility matrix per host (KMP/RN/mobile app) for each migrated flow?
4. What release gating is required before removing duplicated native flow screens?
## Proposed Near-Term PR Slices
1. Host contract + callback schema standardization.
2. RN and KMP smoke tests aligned to the same launch/callback assertions.
3. First euclid-web-only flow segment integrated into both hosts.
## Notes
This is intentionally incomplete. Add decisions and open items as migration discoveries are made.

17
specs/lottie-dotlottie-migration/REVIEW.md → specs/topics/LOTTIE-DOTLOTTIE-REVIEW.md
View File

@@ -7,6 +7,8 @@
Migration from `lottie-react-native` (Lottie JSON) to `@lottiefiles/dotlottie-react-native` (dotLottie binary `.lottie` format). Also re-enables the iOS e2e CI job and bumps the iOS deployment target from 15.1 → 15.4.
This review is intentionally issue-first and lists only actionable defects/risks.
## Scope
- **app/**: All animation imports switched from `.json` → `.lottie` (via `require()`)
@@ -15,15 +17,6 @@ Migration from `lottie-react-native` (Lottie JSON) to `@lottiefiles/dotlottie-re
- **iOS**: Deployment target 15.1 → 15.4; Podfile.lock updated for `dotlottie-react-native`
- **CI**: iOS e2e job re-enabled
## What looks good
1. **Conversion script** (`app/scripts/convert-to-dotlottie.mjs`) — clean, minimal, logs compression ratios.
2. **`DelayedLottieView` rewrite** — `onLoad`-based play is better than the old 100ms `setTimeout` hack. Legacy prop compat (`autoPlay`/`autoplay`, `onAnimationLoaded`/`onAnimationFinish`) is thoughtful.
3. **Metro deduplication resolver** — resolves SDK animation imports to app's copy to avoid duplicate assets, with fallback to SDK-only animations.
4. **tsup externalization** — correctly externalizes `.json`/`.lottie` so Metro handles them.
5. **Package exports** — `.lottie` exports added with correct condition order (`react-native` → `import` → `require`).
6. **Consistent migration pattern** — every screen follows the same `require()` + eslint-disable pattern.
## Issues to address
### 1. `autoplay` prop logic may cause unintended autoplay
@@ -63,9 +56,3 @@ Treat this as a separate feature track, not a blocking defect in this migration
### 8. iOS e2e re-enable is unrelated
Removing `if: false` from the iOS e2e job is a separate concern. Could be its own commit.
## Minor notes
- eslint-disable comments (`-- binary asset loaded by Metro`) are consistent and helpful
- Test mock change (`() => ({})` → `() => 1`) is correct — Metro `require()` returns numeric asset IDs
- `Gemfile.lock` and `Podfile.lock` diffs are correct for the dependency swap

2
specs/handoff-p1-fixes/SECURITY-HARDENING.md → specs/topics/SECURITY-HARDENING.md
View File

@@ -90,7 +90,7 @@ The NFC scan returns `tagId` (passport chip UID — a unique persistent identifi
### Chunk 6: Person 4 Crypto Tracking
**Priority:** Low
**Files:** `specs/person4-sdk-core/`
**Files:** `specs/projects/sdk/workstreams/sdk-core/`
The Person 4 workstream has pending crypto work. In a zero-knowledge/passport-verification SDK, partially-wired crypto paths can degrade security guarantees. This needs a tracking issue or explicit deferral decision.