Compare commits
7
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jason Woltjeandmos-dt-0
|
b6c12bdfcb | ||
|
30a694358d | ||
|
|
e01dfa0cd7 | ||
|
|
6c4a2eb626 | ||
|
mos-dt-0
|
9185b0cce4 | ||
|
mos-dt-0andClaude Fable 5
|
8925a502ae | ||
|
shaggy (mosaic-dev box)andClaude Opus 4.8
|
a45f53071a |
@@ -0,0 +1,115 @@
|
||||
# WebUI Phase P — File / Folder Structure & Migration Map
|
||||
|
||||
> **Status:** living document — first pass. Structure and increment status are verified against
|
||||
> `next` as of merge `8c27024d`. Details (per-surface component inventories, exact route tables,
|
||||
> test matrices) are still being fleshed out; extend the stub sections below rather than rewriting
|
||||
> the verified structure.
|
||||
|
||||
## 1. What Phase P is
|
||||
|
||||
Phase P migrates the Mosaic **web UI** (`apps/web`) from the legacy **Next.js App Router** app to a
|
||||
**Vite + React Router single-page app (SPA)** that the **Gateway serves same-origin** on
|
||||
`:14242`. The RFC splits the work into **six increments (P1–P6)**; the P1 PR title records this as
|
||||
"increment 1/6".
|
||||
|
||||
The migration is deliberately **incremental and non-destructive**: the new SPA is built up
|
||||
_beside_ the existing Next app, sharing one `apps/web/src/lib` networking/auth layer, until the
|
||||
final cutover (P5) removes the Next tree. At every point in between, **both app trees exist in the
|
||||
same package** — this is intentional, not drift.
|
||||
|
||||
## 2. Current tree on `next` (dual-app, transitional)
|
||||
|
||||
```
|
||||
apps/web/
|
||||
├── next.config.ts # legacy Next.js config (removed at P5)
|
||||
├── vite.config.ts # SPA build + DEV proxy config (canonical from P5)
|
||||
├── package.json # dev/build default to NEXT today; :vite variants opt in
|
||||
└── src/
|
||||
├── main.tsx # ── SPA entry (Vite)
|
||||
├── routes.tsx # ── SPA React Router route table
|
||||
├── spa/ # ── NEW SPA surfaces
|
||||
│ ├── guards.tsx # guest / authenticated route guards
|
||||
│ ├── pages/ # login, register, sso-callback (P2); chat + error boundary (P3)
|
||||
│ └── chat/ # P3 typed chat: use-chat-connection, commands-panel,
|
||||
│ # session-panel, message-transcript, tool-call-list, composer
|
||||
│
|
||||
├── lib/ # ── SHARED by BOTH trees (origin-relative networking + auth)
|
||||
│ ├── api.ts # fetch wrapper — relative /api/...
|
||||
│ ├── socket.ts # Socket.IO singleton — relative /chat
|
||||
│ ├── auth-client.ts # BetterAuth client — relative /api/auth/...
|
||||
│ ├── auth-redirect.ts # post-auth redirect resolution (protocol-relative rejected)
|
||||
│ ├── chat-contract.ts # P3 typed chat wire contract (runtime-guarded)
|
||||
│ ├── sso.ts · types.ts · cn.ts
|
||||
│
|
||||
├── app/ # ══ LEGACY Next.js App Router (removed at P5)
|
||||
│ ├── (auth)/{login,register}/
|
||||
│ ├── (dashboard)/{admin,chat,projects,projects/[id],settings,tasks}/
|
||||
│ ├── auth/provider/[provider]/
|
||||
│ └── layout.tsx · page.tsx · globals.css
|
||||
│
|
||||
├── components/ # ══ LEGACY Next component library (auth, chat, layout,
|
||||
│ # projects, settings, tasks, ui) — ported into spa/ across P3/P4
|
||||
└── providers/ # ══ theme-provider (legacy; SPA equivalent under providers)
|
||||
```
|
||||
|
||||
Legend: `──` new SPA (keep), `══` legacy Next (removed at P5), shared `lib/` in the middle.
|
||||
|
||||
## 3. Networking / serving model (why it's same-origin)
|
||||
|
||||
- The SPA speaks **origin-relative paths only**: `/api/...`, `/api/auth/...`, `/chat`. No
|
||||
`NEXT_PUBLIC_*` / `VITE_*` origin var, no hard-coded `http://localhost:14242` under
|
||||
`apps/web/src`.
|
||||
- **Dev:** `vite.config.ts` runs a dev-only proxy that forwards those paths to the Gateway (so the
|
||||
SPA on its dev port and the Gateway on `:14242` behave as one origin).
|
||||
- **Prod (target):** the SPA is **same-origin with the Gateway** — the Gateway serves the built
|
||||
static bundle and the API/WS on `:14242`, so no proxy and no CORS. _(The Gateway does not serve
|
||||
the web `dist` yet — adding that is the core of P5; see §5.)_
|
||||
|
||||
## 4. Build scripts (`apps/web/package.json`)
|
||||
|
||||
| Script | Today | Notes |
|
||||
| ----------------------------- | -------------------------------------------- | ------------------------------ |
|
||||
| `dev` | `next dev` | legacy dev server |
|
||||
| `dev:vite` | `vite` | SPA dev server (+ dev proxy) |
|
||||
| `build` | `node ../../scripts/build-web.mjs` | currently a **Next** build |
|
||||
| `build:vite` | `vite build` | SPA production build → `dist/` |
|
||||
| `lint` / `typecheck` / `test` | `eslint src` / `tsc --noEmit` / `vitest run` | tree-agnostic |
|
||||
|
||||
At **P5** the `:vite` variants become the defaults (`dev`→vite, `build`→vite build) and the Next
|
||||
build path is retired.
|
||||
|
||||
## 5. Increment map (P1–P6)
|
||||
|
||||
| # | Increment | Branch | Status |
|
||||
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------- |
|
||||
| **P1** | Vite + React Router skeleton beside Next (entry, router, guards, vitest) | `feat/webui-p1-vite-skeleton` | ✅ merged — PR **#1143** |
|
||||
| **P2** | SPA data layer + same-origin auth (login/register/SSO pages, guards, relative api/socket/auth-client) | `feat/webui-p2-data-auth` | ✅ merged — PR **#1144** |
|
||||
| **P3** | Typed SPA **chat** (`spa/chat/*`, `chat-contract.ts`, chat page + error boundary) | `feat/webui-p3-chat` | 🚧 in progress (unmerged) |
|
||||
| **P4** | Port **projects / tasks / settings / admin** dashboard surfaces into the SPA | _tbd_ | ⏳ not started |
|
||||
| **P5** | **Cutover**: Gateway serves the Vite `dist` on `:14242`; flip `dev`/`build` to vite; **remove** the legacy Next `app/` tree + `next.config.ts` | _tbd_ | ⏳ not started |
|
||||
| **P6** | CI / images (trails): build the SPA in CI, ship images | _tbd_ | ⏳ trails |
|
||||
|
||||
Each increment follows the same delivery pipeline: brief traceable to the RFC → author →
|
||||
**independent** integrator verification (build+test+typecheck+lint) → **independent** code + security
|
||||
review (author ≠ reviewer) → author remediates → branch + PR to `next` → **independent** merge-gate
|
||||
merges. Author self-reports are not trusted; every gate is re-derived independently.
|
||||
|
||||
## 6. Known dependency / blocker
|
||||
|
||||
- **Issue #1145 — Gateway `dist` boot is broken** (DI failure on a defaulted constructor param);
|
||||
the Gateway currently runs **dev-mode only**. This is a **hard precondition for P5**: the Gateway
|
||||
cannot serve the SPA `dist` on `:14242` until `dist` boot works. P3/P4 remain on the dev-proxy
|
||||
topology meanwhile.
|
||||
|
||||
## 7. Not part of Phase P (disambiguation)
|
||||
|
||||
`docs/plans/2026-08-09-webui-fleet-claude-bridge.md` and
|
||||
`docs/scratchpads/webui-fleet-bridge-plan.md` describe a **separate** WebUI ↔ fleet/Claude bridge
|
||||
effort. They are **not** the Phase P SPA migration and should not be conflated with the increments
|
||||
above.
|
||||
|
||||
## 8. Where the detail lives (extend these)
|
||||
|
||||
- Per-increment working notes: `docs/scratchpads/webui-p*-*.md` (e.g. `webui-p2-data-auth.md`).
|
||||
- _Stub — to flesh out:_ per-surface component inventory (which `components/*` port to which
|
||||
`spa/*`), the full SPA route table, the P5 cutover checklist, and the P6 CI/image plan.
|
||||
@@ -39,6 +39,7 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
|
||||
| TypeScript strict typing | `guides/TYPESCRIPT.md` |
|
||||
| QA / test strategy | `guides/QA-TESTING.md` |
|
||||
| Documentation (any code/API/auth/infra change) | `guides/DOCUMENTATION.md` |
|
||||
| Writing style (docs, comms, any prose) | `guides/WRITING-STYLE.md` |
|
||||
| Secrets / vault usage | `guides/VAULT-SECRETS.md` |
|
||||
| Tool/credential reference (service CLIs, wrappers) | `guides/TOOLS-REFERENCE.md` |
|
||||
| Memory protocol (OpenBrain capture/recall) | `guides/MEMORY.md` |
|
||||
|
||||
@@ -27,6 +27,14 @@ Master/slave model:
|
||||
- Do not perform destructive git/file actions without explicit instruction.
|
||||
- Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.
|
||||
|
||||
### Output standards (writing + code)
|
||||
|
||||
- Technical documentation follows **MOS-STE** (Mosaic Simplified Technical English — an adapted ASD-STE100 profile): short sentences, one instruction per sentence, active voice, one word per meaning, one term per concept. Full rules: `~/.config/mosaic/guides/WRITING-STYLE.md`.
|
||||
- Apply MOS-STE **hardest to verification artifacts** (acceptance criteria, witness predicates, gate/alarm conditions). There an ambiguous term produces a false green, not just a confused reader.
|
||||
- Source code follows the **Google Style Guide** for the language.
|
||||
- User-facing comms follow the user's declared `communicationStyle` in `USER.md` "Communication Preferences" (`direct` | `friendly` | `formal`, default `direct`); `guides/WRITING-STYLE.md` §5 maps each value to output. The documentation standard does not change with user preference.
|
||||
- **Carve-out:** MOS-STE does NOT apply to content that must carry a specific human voice (letters, personal or marketing prose, voice-matched output). A declared voice profile wins.
|
||||
|
||||
### Secrets handling (HARD RULE)
|
||||
|
||||
- Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
# Writing Style Standard — MOS-STE (MANDATORY)
|
||||
|
||||
This guide defines how agents write. It sets one style standard per output type.
|
||||
It is written in the standard it defines, as a worked example.
|
||||
|
||||
**Adapted, not compliant.** MOS-STE (Mosaic Simplified Technical English) is an
|
||||
adapted profile of ASD-STE100. Mosaic does not license or certify against
|
||||
ASD-STE100. Mosaic uses the load-bearing rules and fits them to agent work. This
|
||||
is the same stance Mosaic takes toward DO-178B/C: use the rigor, do not claim the
|
||||
certification.
|
||||
|
||||
## Scope — which standard governs which output
|
||||
|
||||
| Output type | Standard |
|
||||
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| Technical documentation (READMEs, runbooks, PRDs, procedures, ADRs, guides, acceptance criteria, design docs) | **MOS-STE** (this guide) |
|
||||
| Source code and code comments | **Google Style Guide** for the language (§4) |
|
||||
| Inter-agent comms | MOS-STE by default (concise, structured) |
|
||||
| User-facing comms | **Per-user style choice** — read `USER.md` "Communication Preferences" (§5) |
|
||||
| End-user prose the user owns (marketing, letters, personal writing, voice-matched content) | The user's declared voice. MOS-STE does NOT apply. |
|
||||
|
||||
**The user-voice carve-out is absolute.** Do not apply MOS-STE to content that
|
||||
must carry a specific human voice (for example a cover letter, a personal
|
||||
message, or marketing copy). That content needs the user's voice. MOS-STE would
|
||||
damage it. When a project declares a voice profile, that profile wins.
|
||||
|
||||
## 1. Why one standard
|
||||
|
||||
Agent documentation drifts across projects. Different agents use different terms,
|
||||
sentence styles, and structures for the same concept. Readers lose time.
|
||||
Assumptions hide in ambiguous prose. One standard gives agents a clear target. It
|
||||
gives reviewers a clear test.
|
||||
|
||||
## 2. Where MOS-STE matters most — verification artifacts
|
||||
|
||||
Apply MOS-STE hardest to acceptance criteria, witness predicates, gate
|
||||
definitions, and alarm conditions. In prose, an ambiguous term produces a
|
||||
confused reader. In a verification artifact, an ambiguous term produces a false
|
||||
green — a check that passes without testing the claim.
|
||||
|
||||
The one-term-one-concept rule (rule 9) is the guard. When one word names two
|
||||
concepts in one predicate, the check can test the wrong concept and still pass.
|
||||
|
||||
**Worked failure.** A rename used a witness predicate with three clauses: ref A
|
||||
present, ref B absent, tip committed from this host. Every clause tested the git
|
||||
_ref_ (the channel). The claim under test was about a _field inside the payload_.
|
||||
The word "beacon" named two concepts in one sentence. Deleting ref B was the next
|
||||
scheduled step. That step flips the last clause green and certifies a state in
|
||||
which the payload still names the wrong host. The predicate was one planned action
|
||||
away from a false green on its normal path. The payload field was never tested.
|
||||
|
||||
Rule: when N failure modes share one observable, the observable is not a
|
||||
diagnostic. In a verification artifact, that ambiguity does not confuse a reader —
|
||||
it certifies the defect.
|
||||
|
||||
## 3. MOS-STE rules
|
||||
|
||||
### 3.1 Sentence rules
|
||||
|
||||
1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or
|
||||
fewer for a description. (Reasoning and doctrine prose relaxes this limit —
|
||||
see §3.4. A future lint enforces §3.1, not §3.4.)
|
||||
2. Write one instruction per sentence. In a procedure, give one command per step.
|
||||
3. Use the active voice. Write "Run the script." Do not write "The script should
|
||||
be run."
|
||||
4. Use the imperative for instructions. Start the sentence with the verb.
|
||||
5. Use simple verb tenses. Prefer the present tense. Avoid the perfect and
|
||||
progressive tenses when a simple tense works.
|
||||
6. Do not use an `-ing` form when it makes the meaning unclear.
|
||||
7. Write positive statements. State what to do, not only what to avoid.
|
||||
|
||||
### 3.2 Word rules
|
||||
|
||||
8. Use one word for one meaning. Do not use the same word in two senses.
|
||||
9. Use one term for one concept. Do not use synonyms for variety. Example: choose
|
||||
`secret`, `credential`, or `key` for each concept, and keep it.
|
||||
10. Use articles (`a`, `the`). Do not drop words to save space.
|
||||
11. Keep an approved-terms glossary per project. Add each domain noun and each
|
||||
chosen verb. Technical names (for example `Vault`, `cgroup`, `systemd`) are
|
||||
always allowed.
|
||||
12. Define an abbreviation at its first use. Then use it consistently.
|
||||
|
||||
### 3.3 Structure rules
|
||||
|
||||
13. Use a list for parallel items or sequential steps. Do not put them in one long
|
||||
sentence.
|
||||
14. Use a table for data with more than two dimensions.
|
||||
15. Use parallel structure in headings and steps.
|
||||
16. Repeat the noun. Do not use a pronoun when the reference is unclear.
|
||||
|
||||
### 3.4 Adaptation notes (where MOS-STE deviates from ASD-STE100, and why)
|
||||
|
||||
- **No licensed dictionary.** ASD-STE100 ships a controlled dictionary under
|
||||
copyright. MOS-STE uses per-project glossaries instead (rule 11).
|
||||
- **Domain terms are allowed.** MOS-STE keeps every term the work needs.
|
||||
- **Reasoning prose gets structure, not amputation.** Apply the sentence and word
|
||||
rules to design and doctrine writing. Allow the length a subtle argument needs.
|
||||
Readable-first beats rule-strict when the two conflict.
|
||||
|
||||
## 4. Code — Google Style Guide
|
||||
|
||||
Write source code to the Google Style Guide for the language (Python, TypeScript,
|
||||
Shell, Go, and so on). Match the existing file when a local convention already
|
||||
exists. Keep code comments to the MOS-STE sentence and word rules.
|
||||
|
||||
## 5. User-facing comms — a per-user choice
|
||||
|
||||
Mosaic is multi-user. Different users want different comms styles. The framework
|
||||
already carries the selectable setting: `communicationStyle` (`direct` |
|
||||
`friendly` | `formal`, default `direct`). `mosaic init` writes it, and the
|
||||
builder renders it into the generated `USER.md` "Communication Preferences"
|
||||
section. This guide adds the OUTPUT meaning of each value; do not invent new
|
||||
values.
|
||||
|
||||
The builder renders the style as prose bullets, not the token name, so match on
|
||||
the leading bullet the generated `USER.md` actually contains:
|
||||
|
||||
| `USER.md` leading bullet | Style | User-facing output |
|
||||
| ----------------------------- | ------------------ | ---------------------------------------------------------------------- |
|
||||
| "Direct and concise" | `direct` (default) | MOS-STE structure — short, active, defined terms, tables for overview. |
|
||||
| "Warm and conversational" | `friendly` | Warmer register. Full sentences, explain reasoning, fewer tables. |
|
||||
| "Professional and structured" | `formal` | Professional and structured. Thorough, with explicit recommendations. |
|
||||
|
||||
This setting governs **user-facing comms only**. It does not change the
|
||||
documentation standard (§3), which is always MOS-STE regardless of the value.
|
||||
|
||||
## 6. Enforcement
|
||||
|
||||
- **Now:** human review only. **No mechanical prose check exists today.** The
|
||||
pre-push gate runs typecheck, lint, build, and tests; it inspects no prose.
|
||||
Reviewers check output against the scope table and the MOS-STE rules by hand.
|
||||
- **Future:** an MOS-STE lint check (built from the §3.1 sentence rules) and a
|
||||
Google-style linter in the pre-push gate. A future linter enforces §3.1, not
|
||||
§3.4 — see the note at rule 1.
|
||||
Reference in New Issue
Block a user