pat/wursor
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

docs: record decisions ADR 0018-0021 (Next.js, sign-in methods, WeOwn Cloud, no-diff rule) and align PRD, guide and AGENTS.md

Browse Source 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014SdXCbrN5PtGExkpvMaMHx
This commit is contained in:
Claude
2026-10-12 14:35:01 +00:00
parent 9772724268
commit 1634763180
10 changed files with 148 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+6 -3
View File
@@ -10,7 +10,7 @@ Non-technical WordPress site owners describe what they want; Wursor makes it hap
```
api/ Node.js + TypeScript API server (empty until Phase 0 gate)
web/ React + TypeScript frontend (empty until Phase 0 gate)
web/ Next.js (App Router) + TypeScript frontend (ADR 0018)
plugin/ WordPress plugin (PHP) — empty until Phase 0 gate
infrastructure/ Docker images, warm pool, GC, deploy scripts
e2e/ Playwright + e2e/golden/ harness
@@ -46,8 +46,11 @@ The `.agents/skills/` directory is a family of rigor skills modeled on Cursor's
## Stack notes
- Backend: Node.js + TypeScript, Express/Fastify, PostgreSQL (Wursor data), Redis (SSE/queue)
- Frontend: React + TypeScript, Vite
- Backend: Node.js + TypeScript, Fastify (Wursor API), PostgreSQL (Wursor data), Redis (SSE/queue)
- Frontend: Next.js (App Router) + React + TypeScript. Server layer holds tokens; browser gets a session cookie only (ADR 0018). Existing Vite shell is being migrated.
- Sign-in: emailed 8-character code, emailed link and passkeys (ADR 0019)
- Cloud sites: provisioned on WeOwn Cloud behind the platform interface (ADR 0020)
- Direction: see PRD.md (Headless, revision 4) and IMPLEMENTATION.md section 0
- Sandboxes: Docker on VPS, pre-baked WordPress image, overlayfs layers, media proxied (not copied)
- Plugin: standard WordPress PHP plugin, REST API + token auth
- Tests: vitest (api, web), phpunit (plugin), Playwright (e2e)
CHANGELOG.md
+1
View File
@@ -8,6 +8,7 @@ The project is pre-1.0. Versions below `1.0.0` are internal milestones, not publ
### Added
- ADRs 0018 to 0021: Next.js web app (partly supersedes ADR 0011), sign-in by code, link and passkeys, Cloud provisioning on WeOwn Cloud, and keeping the "never sees a diff" rule wording. PRD, IMPLEMENTATION and AGENTS.md updated to match.
- `docs/prd-assets/headless-architecture.png`, the architecture diagram used in the PRD.
- Design reference: Figma file "Wursor - Experiment" (Design system, Product Design, Marketing site and Brand Guideline pages).
- **Monorepo workspace** — `pnpm` workspace (`api`, `web`, `e2e`), root `package.json` / `pnpm-workspace.yaml` / `tsconfig.base.json`, and a PHP `plugin` package (`composer.json`). Empty packages by design (see [ADR 8](docs/decisions/0008-empty-packages-not-stubs.md)).
IMPLEMENTATION.md
+7 -7
View File
@@ -48,19 +48,19 @@
### 0.2 Decisions to ratify before building on them
These conflict with existing ADRs or code and need a written decision (add ADRs 0018 onward) before work starts.
These conflicted with existing ADRs or code. All four were decided on October 12, 2026 and recorded as ADRs 0018 to 0021.
1. **Next.js versus React + Vite.** [ADR 0011](docs/decisions/0011-fastify-react-stack.md) chose Fastify and React. Headless rev 4 needs a server layer for token handling. Options: adopt Next.js, or keep Vite and add a small backend-for-frontend inside the API. Decide before more of `web/` is built.
2. **Sign-in method.** The design uses an emailed 8-character code. HL-03 still says passkey or emailed link (PRD D-HL-13).
3. **Who provisions Cloud sites.** WeOwn Cloud infrastructure or a partner behind the same interface (PRD D-HL-7). Do not build the hosting plane until this is decided.
4. **"The user never sees a diff" (AGENTS.md rule 3).** The PRD keeps technical detail one tap away in an expandable section for owners who want it. Confirm the wording of the rule.
1. **Decided: Next.js ([ADR 0018](docs/decisions/0018-nextjs-web-app.md)).** Was: Next.js versus React + Vite. [ADR 0011](docs/decisions/0011-fastify-react-stack.md) chose Fastify and React. Headless rev 4 needs a server layer for token handling. Options: adopt Next.js, or keep Vite and add a small backend-for-frontend inside the API. Decide before more of `web/` is built.
2. **Decided: code, link and passkeys ([ADR 0019](docs/decisions/0019-sign-in-methods.md)).** Was: sign-in method. The design uses an emailed 8-character code. HL-03 still says passkey or emailed link (PRD D-HL-13).
3. **Decided: WeOwn Cloud ([ADR 0020](docs/decisions/0020-weown-cloud-provisioning.md)).** Was: who provisions Cloud sites. WeOwn Cloud infrastructure or a partner behind the same interface (PRD D-HL-7). Do not build the hosting plane until this is decided.
4. **Decided: leave the wording ([ADR 0021](docs/decisions/0021-keep-no-diff-rule-wording.md)).** Was: "The user never sees a diff" (AGENTS.md rule 3). The PRD keeps technical detail one tap away in an expandable section for owners who want it. Confirm the wording of the rule.
### 0.3 How the existing sprints map
| Existing work | Status under the new direction |
| :--- | :--- |
| Phase 0 spikes and golden harness | Keep as they are. |
| Sprint 1, web app scaffold and sandbox orchestration | Keep the sandbox work. Revisit the scaffold after decision 0.2.1. |
| Sprint 1, web app scaffold and sandbox orchestration | Keep the sandbox work. Move the web scaffold to Next.js (ADR 0018). |
| Sprint 2, WordPress plugin connector | Keep. Extend `site-info` to report the access level (Full access or Content only) and the operations the site supports. Wrap it behind the platform interface. |
| Sprint 3, agent orchestrator and playbooks | Keep. Add the pre-run access check so a task that needs more access stops in the composer before any run starts. |
| Sprints 4 and 5, content and design playbooks | Keep. Design playbooks gain the new-site path: a five-question brief and three design directions. |
@@ -76,7 +76,7 @@ These conflict with existing ADRs or code and need a written decision (add ADRs
| C | Identity: sign-up, sign-in, verify states, workspace naming, then Home. | PX-01, PX-02 |
| D | Evidence-bound approval and the Publish entry point on desktop and mobile. | PX-03, SH-10 |
| E | New-site path on Cloud: brief, three design directions, build on a safe copy, preview, approval. | SH-03 |
| F | Hosting plane: provisioning, temporary address, backups, domain connection. Blocked on 0.2.3. | SH-04, SH-12, SH-14 |
| F | Hosting plane: provisioning, temporary address, backups, domain connection. Unblocked by ADR 0020; staffing readiness still applies. | SH-04, SH-12, SH-14 |
| G | Moves in both directions as releases, with dry run, page-by-page comparison and rollback. | SH-08 to SH-11 |
| H | Surfaces: Home, Sites, Activity, Board with calendar, Settings, command palette, system states. | PX-04 to PX-08 |
| I | Mobile and dark parity audits, accessibility scan, touch-target and contrast checks. | PX-09 to PX-12 |
PRD.md
+5 -5
View File
@@ -653,7 +653,7 @@ PKCE is a standard, secure sign-in method for browser apps. It protects the code
1. The person selects Sign in. The Next.js server generates a code verifier and challenge, a state value and a nonce, stores them in a short-lived encrypted cookie and redirects the browser to the Wursor identity service.
2. The identity service authenticates the person with a passkey or an emailed link. In V1 it also accepts single sign-on from a company identity provider.
2. The identity service authenticates the person with an emailed 8-character code, an emailed link or a passkey (ADR 0019). In V1 it also accepts single sign-on from a company identity provider.
3. The identity service redirects back with a code. The Next.js server validates the state, exchanges the code and verifier for tokens, validates the identity token and creates a session record on the server.
@@ -1062,7 +1062,7 @@ These requirements apply only to the Headless pattern in this revision. They rep
|---|---|---|---|
| HL-01 | The frontend is a Next.js application (App Router, TypeScript) deployed on its own domain, separate from every target platform. | MVP | The full core journey (create task, watch run, preview, review, approve) works in an environment where no WordPress site is part of the application stack. |
| HL-02 | Wursor owns its control plane. Users, organizations, projects, tasks, approvals, policies and the audit log are stored in Wursor's own database (PostgreSQL) and served by the Wursor API. No product data is stored inside a customer's site. | MVP | Removing the connector plugin from a customer site deletes no Wursor records. A database restore drill recovers the control plane with no access to any customer site. |
| HL-03 | Identity is Wursor-owned. People sign in with passkeys or an emailed link. The Next.js server and the identity service use the authorization code flow with PKCE. Single sign-on (OIDC or SAML) is added in V1. | MVP | Sign-in works with no WordPress account. A test that submits a wrong code verifier is rejected, and a replayed authorization code is rejected. |
| HL-03 | Identity is Wursor-owned. People sign in with an emailed 8-character code, an emailed link or a passkey (ADR 0019). The Next.js server and the identity service use the authorization code flow with PKCE. Single sign-on (OIDC or SAML) is added in V1. | MVP | Sign-in works with no WordPress account. A test that submits a wrong code verifier is rejected, and a replayed authorization code is rejected. |
| HL-04 | A backend for frontend holds all access and refresh tokens on the server. The browser receives only an HttpOnly session cookie and, while watching a run, a stream token. | MVP | Scans of browser storage, page source and responses during an end-to-end run find no access or refresh token. |
| HL-05 | The API is contract-first. An OpenAPI description in the repository is the source of truth, and the typed client, request validators and mock server are generated from it. | MVP | Contract tests call the real Wursor API and Conductor with generated requests and validate responses. A breaking change without a version bump fails CI. |
| HL-06 | The browser opens event streams directly to the Conductor with a two-minute, run-scoped stream token sent in an Authorization header, and resumes after a drop from the last event number. | MVP | Across 50 forced disconnects, no event is lost or duplicated, and tokens never appear in access logs. |
@@ -1130,13 +1130,13 @@ These requirements apply only to the Headless pattern in this revision. They rep
| D-HL-4 | How the connector plugin is distributed: WordPress.org directory, direct download, or both. | M1 | Product |
| D-HL-5 | Which backup method the WordPress target relies on first, and whether a fleet connector supplies it. | Phase 0 | Product |
| D-HL-6 | Whether single sign-on arrives at V1 or earlier for design-partner customers. | M2 | Product |
| D-HL-7 | How Cloud sites are provisioned for the first release: on WeOwn Cloud infrastructure, or through a partner (WordPress.com, InstaWP, a managed host API) behind the same interface. Recommended: WeOwn Cloud only if on-call, patching and abuse handling are staffed from the first customer; otherwise a partner first. | Phase 0 | CTO |
| D-HL-7 | **Decided (ADR 0020, October 12, 2026): WeOwn Cloud.** Cloud sites are provisioned on WeOwn Cloud infrastructure behind the same interface. The condition in section 5.3 still applies: on-call, patching and abuse handling staffed from the first customer. | Phase 0 | CTO |
| D-HL-8 | Plans and prices: hosted and connect-only plans, work allowances, backup retention beyond 30 days, and what a free trial includes. Draft numbers in the design are placeholders. | M2 | Product and finance |
| D-HL-9 | Whether WordPress.com sign-in is in the MVP or the connector plugin only. Recommended: both, because WordPress.com is the shortest path for non-technical owners; verify capabilities in Phase 0. | Phase 0 | Product |
| D-HL-10 | Retention after a move out: 30 days live and read-only, then 30 days archived (proposed). | M2 | Product and legal |
| D-HL-11 | Temporary address scheme and search-engine policy for Cloud sites before a domain is connected. | M2 | Engineering lead |
| D-HL-12 | Acceptable-use policy, abuse handling and availability target for Cloud sites. | M2 | Operations and legal |
| D-HL-13 | Whether sign-in uses an emailed 8-character code (as designed), an emailed link (as HL-03 says), or both. Recommended: the code, with the link as a fallback on mobile, and update HL-03. | M0 | Product and engineering |
| D-HL-13 | **Decided (ADR 0019, October 12, 2026):** support the emailed 8-character code, the emailed link and passkeys. Build order: code, link, passkeys. HL-03 updated. | M0 | Product and engineering |
| D-HL-14 | Cloud storage allowance per plan, and whether hosting is included in every plan. The billing screens show sample numbers only. | M2 | Product and finance |
| D-HL-15 | Whether the theme follows the device only, or also offers a manual light and dark switch in Settings. | M1 | Design |
| D-HL-16 | Whether the marketing pages move onto the product prototype so that landing page to onboarding can be walked as one flow, or stay separate and link by address. | Now | Design |
@@ -1191,7 +1191,7 @@ This section records what the screen-level design contains, so that engineering,
| **Gap** | **What is missing or different** | **Where decided** |
|---|---|---|
| Sign-in method | The design uses an emailed 8-character code. HL-03 says passkey or emailed link. | D-HL-13 |
| Sign-in method | Resolved by ADR 0019: code, link and passkeys are all supported. The designed screens cover the code; link and passkey screens still need design. | D-HL-13 |
| Calendar extras | Not yet designed: drag to reschedule, an empty month, and a day with more than three changes. | PX-05 |
| Mobile preview toolbar | Tag and device toggles are hidden on mobile to make room for Publish. | PX-09 |
| Touch size | Icon buttons are 36 px, below the 44 px target. | PX-09 |
docs/decisions/0011-fastify-react-stack.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 11. Fastify is the API server; React + Vite is the web shell
- **Status:** Accepted
- **Status:** Partially superseded by [ADR 0018](0018-nextjs-web-app.md) (the React + Vite web shell). Fastify for `api/` stands.
- **Date:** 2026-08-15
## Context
docs/decisions/0018-nextjs-web-app.md
+36
View File
@@ -0,0 +1,36 @@
# 18. The web app is Next.js (App Router); Fastify stays as the Wursor API
- **Status:** Accepted
- **Date:** 2026-10-12
- **Supersedes:** the web half of [ADR 0011](0011-fastify-react-stack.md). The Fastify half stands.
## Context
PRD Headless revision 4 (HL-01, HL-04, HL-07, HL-08, HL-15) requires a web app with a server layer that holds access and refresh tokens, so the browser only ever sees an HttpOnly session cookie and, while watching a run, a two-minute stream token. It also requires dynamically rendered authenticated pages that are never shared-cached, CSRF protection on state-changing requests, static marketing pages, and an installable PWA. [ADR 0011](0011-fastify-react-stack.md) chose React + Vite, which is a client-only shell with no server layer. `web/` currently holds the Sprint 1 and Sprint 2 components and hooks (signup, chat, preview, approve, site connector).
## Decision
Build the web app on **Next.js (App Router, TypeScript)**. Keep **Fastify** for the Wursor API in `api/`. Keep vitest and Testing Library for unit and component tests, and Playwright for end to end.
The Next.js server is the backend for frontend: it owns the session, holds tokens, validates input against the OpenAPI contract and calls the Wursor API on the person's behalf. It makes no authorization decisions; the Wursor API rechecks every permission. Run streams go directly from the browser to the Conductor, never through Next.js.
Existing `web/` React components and hooks are kept and moved under the Next.js app. The Vite shell is retired once the Next.js app serves the same screens.
### Options considered
- **Next.js (chosen).** Matches the PRD as written. Server Components, server actions and route handlers give the token-holding layer, per-request rendering and static marketing pages in one framework, and the team already writes React and TypeScript.
- **Keep Vite and add a backend for frontend inside the Fastify API.** Smallest change to the repo, and one fewer framework. It puts session and cookie handling in the API, which the PRD wants kept separate from the control plane, and leaves marketing pages, SEO and PWA scope to be rebuilt by hand.
- **Vite plus a separate small BFF service.** Clean separation, but one more deployable for a small team, which the PRD's risk register already flags.
### Rejected
- Keeping Vite alone: it cannot satisfy HL-04 (no tokens in the browser).
- A separate BFF service: extra deployable with no benefit over the Next.js server layer.
## Consequences
- `web/` becomes a Next.js app. The migration is step C and H in [IMPLEMENTATION.md](../../IMPLEMENTATION.md) section 0.4; existing Sprint 1 and 2 screens move first, and the in-memory session token flow from Sprint 1 is replaced by server-held sessions.
- `web/package.json` changes its dev, build and start scripts. Tests stay on vitest.
- The 90% coverage floor for `web/` continues to apply. Server Components and server actions are tested at the unit level where possible and covered by Playwright otherwise.
- Hosting for the Next.js app must support server rendering and streaming responses (PRD section 21).
- No more Vite-specific code is added to `web/` from this point.
docs/decisions/0019-sign-in-methods.md
+37
View File
@@ -0,0 +1,37 @@
# 19. Sign-in supports an emailed code, an emailed link and passkeys
- **Status:** Accepted
- **Date:** 2026-10-12
## Context
The PRD text (HL-03) says people sign in with a passkey or an emailed link. The finished design (PX-01, PX-02) uses an emailed 8-character code with separate empty, filled, wrong, expired and resent states, and Google sign-in on both paths. Open decision D-HL-13 asked which to use.
## Decision
Support all three methods, behind one identity service and one authorization code flow with PKCE:
1. **Emailed 8-character code.** The designed default. Single use, expires, rate limited, ten wrong attempts lock the attempt (PX-02).
2. **Emailed link.** The same one-time secret delivered as a link. Offered as the fallback, especially on mobile where opening the mail app and typing a code is awkward.
3. **Passkeys.** Offered after a first successful sign-in, and required for roles that approve once enrolled (ID-02).
Google sign-in stays as designed (PX-01). No method depends on a WordPress account.
Build order: code first because it matches the screens, then the link, then passkeys. Each method is complete and tested before the next starts.
### Options considered
- **All three (chosen).** Covers the designed screens, a mobile fallback and the stronger credential, at the cost of three flows to test and maintain.
- **Code only.** Matches the design exactly and is the smallest build, but gives no phishing-resistant option.
- **Passkey or link only, as HL-03 was written.** Contradicts the screens already designed.
### Rejected
- Passwords: not in the PRD and not wanted for non-technical owners.
## Consequences
- PRD HL-03 and D-HL-13 are updated to match; PRD 26.4 no longer lists the sign-in method as a gap.
- Whether the identity service is bought or built (D-HL-1) is still open. The recommendation in the PRD is to buy a managed provider that supports all three; confirm that it supports an 8-character code with the designed states before choosing, or build that part.
- The unknown-email state must never reveal whether an account exists (PX-01), for every method.
- Tests must cover wrong, expired, reused and rate-limited codes, a replayed authorization code and a wrong PKCE verifier, for each method.
docs/decisions/0020-weown-cloud-provisioning.md
+28
View File
@@ -0,0 +1,28 @@
# 20. Cloud sites are provisioned on WeOwn Cloud
- **Status:** Accepted
- **Date:** 2026-10-12
## Context
PRD decision D-HL-7 asked whether Wursor Cloud sites are provisioned on WeOwn Cloud infrastructure or through a partner (WordPress.com, InstaWP, a managed host API) behind the same interface. The hosting plane (steps F and G in [IMPLEMENTATION.md](../../IMPLEMENTATION.md) section 0.4) was blocked on this answer. The PRD recommended WeOwn Cloud only if on-call, security patching and abuse handling are staffed from the first customer.
## Decision
Provision Cloud sites on **WeOwn Cloud**. The hosting plane is a separate environment from the execution plane and is reached only through the platform interface's `provision` operation (SH-16), so the choice is replaceable.
### Options considered
- **WeOwn Cloud (chosen).** Most control and the cleanest story for customers who care about owning their stack. Largest operational load.
- **Partner provisioning first.** Fastest start and least operational risk, with less control over price and behavior. Not chosen.
### Rejected
- Partner provisioning for the first release: Wursor is working with WeOwn Cloud.
## Consequences
- The hosting plane work (SH-04, SH-12, SH-14) is unblocked and can be planned. It is the largest new commitment, and the PRD's rollout plan puts hardening at about 46 weeks.
- The staffing condition in the PRD still stands and is now an open readiness item, not a reason to delay the decision: on-call, patching to the 72-hour target, abuse handling, backups verified by restore tests and a support path must exist before the first Cloud customer (PRD 5.3 and risk "Hosting makes Wursor an operations business").
- The `provision` operation stays behind the interface, so a partner backend can be added later without changing the product (SH-16, V2).
- Cap the number of Cloud sites per plan during beta, as the PRD risk register proposes.
docs/decisions/0021-keep-no-diff-rule-wording.md
+22
View File
@@ -0,0 +1,22 @@
# 21. Keep the "never sees a diff" rule in AGENTS.md as written
- **Status:** Accepted
- **Date:** 2026-10-12
## Context
AGENTS.md hard rule 3 says the user never sees a diff, a terminal, a settings screen or an error log. PRD Headless revision 4 keeps technical detail (diffs, hashes, logs, traces) one tap away in an expandable section for owners who want it (section 16, RV-01). IMPLEMENTATION section 0.2 asked whether the rule's wording should change.
## Decision
Leave rule 3 as it is. It describes the default experience and the test for any change: if a change would put engineer-only UI in front of a non-technical owner by default, it is wrong. The optional, collapsed technical detail in the PRD is read as consistent with that default.
### Options considered
- **Leave the wording (chosen).**
- Reword to "by default" and mention the expandable detail. Not chosen.
## Consequences
- AGENTS.md rule 3 is unchanged.
- Reviewers apply the rule to the default view. The expandable technical section must never be the only way to complete a task, and must be collapsed unless the person opens it.
docs/decisions/README.md
+5 -1
View File
@@ -24,13 +24,17 @@ Each ADR is a single file following the [Nygard format](https://cognitect.com/bl
| [0008](0008-empty-packages-not-stubs.md) | Workspace ships empty packages, not placeholder source | Accepted |
| [0009](0009-repo-rename.md) | Repository renamed originmain → wursor | Accepted |
| [0010](0010-openrouter-live-golden.md) | Golden harness scores live runs through a provider-agnostic LLM client (OpenRouter first) | Accepted |
| [0011](0011-fastify-react-stack.md) | Fastify is the API server; React + Vite is the web shell | Accepted |
| [0011](0011-fastify-react-stack.md) | Fastify is the API server; React + Vite is the web shell | Partially superseded by [0018](0018-nextjs-web-app.md) (web half) |
| [0012](0012-in-memory-user-store.md) | In-memory user store behind a UserStore interface; Postgres deferred | Accepted |
| [0013](0013-docker-boundary-mock.md) | Sandbox orchestration mocks the Docker boundary; real daemon client deferred | Accepted |
| [0014](0014-postgres-queryable.md) | Postgres user store via a Queryable boundary; schema in SQL migrations | Accepted |
| [0015](0015-dockerode-engine-gating.md) | Docker daemon client via dockerode behind an injected engine; sandbox gated by env | Accepted |
| [0016](0016-pairing-code-ownership.md) | Pairing-code TTL/lockout lives on the Wursor API; the plugin enforces token/HMAC/scope | Accepted |
| [0017](0017-semantic-tool-schema.md) | The agent is given a semantic, allowlisted tool schema — not a raw wp_cli surface | Accepted |
| [0018](0018-nextjs-web-app.md) | The web app is Next.js (App Router); Fastify stays as the Wursor API | Accepted |
| [0019](0019-sign-in-methods.md) | Sign-in supports an emailed code, an emailed link and passkeys | Accepted |
| [0020](0020-weown-cloud-provisioning.md) | Cloud sites are provisioned on WeOwn Cloud | Accepted |
| [0021](0021-keep-no-diff-rule-wording.md) | Keep the "never sees a diff" rule in AGENTS.md as written | Accepted |
## How to add one