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

Justin/update specs rd3 (#1813)

Browse Source 
* update archive

* finslize specs
This commit is contained in:
Justin Hernandez
2026-03-05 16:25:49 -08:00
committed by GitHub
parent a367e7eecb
commit 536eb69538
9 changed files with 15 additions and 691 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
specs/ARCHIVE.md
View File

@@ -4,6 +4,8 @@ Append-only log of retired specs. When a spec is fully done and no longer needed
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) |
| --------------------------- | ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------- |
| `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 |
| 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 |
| `specs/projects/sdk/SPEC-AGENT-OPTIMIZATION.md` | 2026-03-05 | Agent-optimization rollout completed | All 6 execution chunks marked done; canonical guidance consolidated and stale scaffold reduced | N/A |
| `specs/projects/kmp/*` | 2026-03-05 | KMP specs retired from active project tree | KMP planning/execution remains under SDK workstreams; historical KMP context kept in `specs/archive/kmp/` | N/A |

88
specs/EUCLID-WEB-CONSOLIDATION.md
View File

@@ -1,88 +0,0 @@
# 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.

162
specs/SPECS-REORG-PLAN.md
View File

@@ -1,162 +0,0 @@
# Specs Folder Reorganization Plan (Project-First)
Last updated: March 5, 2026
Owner: SDK/specs maintainers
Status: Proposed
## 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
workstreams/
webview/
native-shells/
integrations/
sdk-core/
rn-sdk/
kmp/
INDEX.md
KMP-ARCHITECTURE.md
KMP-INITIATIVE.md
KMP-REORG-PLAN.md
status/
KMP-STATUS.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/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/*`
KMP project:
- `specs/KMP-STATUS.md` -> `specs/projects/kmp/status/KMP-STATUS.md`
- `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/EUCLID-WEB-CONSOLIDATION.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]-|KMP-STATUS.md|lottie-dotlottie-migration|EUCLID-WEB-CONSOLIDATION" specs`
- `rg -n "\]\(\./" specs` (relative-link sanity)
## Immediate Next Steps
1. Create project `INDEX.md` files for `sdk`, `kmp`, `lottie`, `euclid`.
2. Move `KMP-STATUS.md` into `projects/kmp/status/`.
3. Move `lottie-dotlottie-migration/REVIEW.md` into `projects/lottie/`.
4. Move `EUCLID-WEB-CONSOLIDATION.md` into `projects/euclid/`.

17
specs/archive/kmp/INDEX.md
View File

@@ -2,7 +2,9 @@
Last updated: March 5, 2026
Owner: KMP program
Status: Active
Status: Archived
This folder is a historical snapshot. Active execution moved to SDK specs.
## Start Here
@@ -10,21 +12,22 @@ Status: Active
2. [KMP Architecture](./ARCHITECTURE.md) — technical boundaries and runtime model.
3. [KMP Reorg Plan](./REORG-PLAN.md) — migration phases and execution checklist.
## Canonical Paths
## Historical Paths (Retired)
- `specs/projects/kmp/INITIATIVE.md`
- `specs/projects/kmp/ARCHITECTURE.md`
- `specs/projects/kmp/REORG-PLAN.md`
## Active Paths
- `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
## Notes
- 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.
- Keep this folder as immutable historical context.
- For new KMP work, update SDK specs under `specs/projects/sdk/`.
## Migration Tracking

0
specs/projects/sdk/SPEC-AGENT-OPTIMIZATION.md → specs/archive/sdk/SPEC-AGENT-OPTIMIZATION.md
View File

104
specs/projects/kmp/KMP-ARCHITECTURE.md
View File

@@ -1,104 +0,0 @@
# 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 `KMP-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.

96
specs/projects/kmp/KMP-INITIATIVE.md
View File

@@ -1,96 +0,0 @@
# 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
- `KMP-SPECS-INDEX.md`
- `KMP-ARCHITECTURE.md`
- `KMP-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/projects/kmp/KMP-REORG-PLAN.md
View File

@@ -1,190 +0,0 @@
# 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/KMP-ARCHITECTURE.md`
- `specs/projects/kmp/KMP-INITIATIVE.md`
- `specs/projects/kmp/status/KMP-STATUS.md`
- `specs/projects/kmp/workstreams/*`
- `specs/projects/kmp/KMP-SPECS-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. `KMP-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. `KMP-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 `KMP-ARCHITECTURE.md` and `KMP-INITIATIVE.md` skeletons.
- Publish `KMP-SPECS-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.

41
specs/projects/kmp/KMP-SPECS-INDEX.md
View File

@@ -1,41 +0,0 @@
# KMP Specs Index
Last updated: March 5, 2026
Owner: KMP program
Status: Draft
## Start Here
1. `KMP-INITIATIVE.md` — goals, scope, milestones.
2. `KMP-ARCHITECTURE.md` — technical boundaries and runtime model.
3. `KMP-REORG-PLAN.md` — migration phases and execution checklist.
## Canonical Paths
- `specs/projects/kmp/KMP-INITIATIVE.md`
- `specs/projects/kmp/KMP-ARCHITECTURE.md`
- `specs/projects/kmp/KMP-REORG-PLAN.md`
- `specs/projects/kmp/status/KMP-STATUS.md` (planned)
- `specs/projects/kmp/workstreams/` (planned)
- `specs/projects/kmp/KMP-DECISIONS.md` (planned)
- `specs/projects/kmp/KMP-CHANGELOG.md` (planned)
## 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
- [ ] Status moved to `specs/projects/kmp/status/KMP-STATUS.md`
- [ ] Workstreams reorganized under `specs/projects/kmp/workstreams/`
- [ ] Legacy path mapping added to top-level `specs/README.md`
## Change Log
- 2026-03-05: Initial KMP spec index skeleton created.