lhumina_code/hero_assistance
0
0
Fork 0
Code Issues 6 Pull requests Projects Releases Packages Wiki Activity Actions

docs(spec): Phase 18 — vision + executable spec + architecture + testing pyramid (freezone pattern) #5

New issue
Closed
opened 2026-05-01 02:16:02 +00:00 by mik-tf · 4 comments
mik-tf commented 2026-05-01 02:16:02 +00:00
Owner
Copy link

Why

We've built the engineering-discipline pieces of the multi-session pipeline (CLAUDE.md / prompt.md / decisions / limitations / sessions / kickstart / handoff / start / stop). What we're missing is the product-spec layer — a stakeholder-facing document that maps every user-facing behaviour to a verification across the test pyramid.

The pattern this issue adopts: znzfreezone_deploy/docs/dev/e2e_checklist.md — 1860 lines, 30+ sections, ~600-row matrix, 5-column row state schema (Schema? / Wired? / MCP? / Browser? / Human?), audit-log at the top, stakeholder-first framing. Tracking issue #86 for context.

What makes this exemplary:

  1. Vision and checklist live in different files. Conflict-resolution rule: checklist wins (it's what ships); vision wins on future-tense statements.
  2. Stakeholder-first framing — Management/Sales / Legal / Operations / Engineering / Partners get reading instructions; non-engineer can navigate.
  3. Five-column row state replaces 3-column legacy. Maps 1:1 to the testing layers. [skip: REASON] mandatory for opt-out.
  4. Audit log at the top is reverse-chronological; every ✅→❌ flip is recorded with reason. Self-correcting documentation.
  5. Executive UX summary as narrative paragraphs (sections 1–13). Vision and verification stay in lockstep.
  6. One-line summary: the elevator pitch.

Goal

Bring hero_assistance to "ship-ready" parity with the freezone documentation pattern. After this issue lands:

  • Every user action ("file a ticket", "see live presence", "paste an image") has a row in the checklist with a 5-column verification status
  • Every Phase 16+ deliverable references the rows it's making green
  • Every regression flips a column with strikethrough + reason — the audit trail is permanent
  • Non-engineer stakeholders can read the doc and know what works

Deliverables

1. docs/vision/HERO_ASSISTANCE.md (new, ~600 lines)

The freezone analog: why this product exists.

  • Principles (6-8): peer-to-peer (no central tracker), mycelium-bound (no public IPs), embed-as-Support-tab, schema-per-customer, AI-amenable (every action → MCP tool), config-as-code, "looks amazing" UI bar, no-rebuild-for-new-customer.
  • Milestones: v0.1 (backend complete, Phase 14 ✅), v0.2 (UI ready + Phase 16 polish), v0.3 (auth split — #4), v0.4 (E2E test suite — #3), v1.0 (one paying customer in production).
  • Industry positioning: Zendesk / Intercom / Linear customer portal. What we are; what we deliberately aren't. The "no central tracker" stance distinguishes us.
  • Decisions index — links to D-01..D-18, organized by topic.
  • Future-tense section — what's not v1 (cross-project federation, SSO, mobile native).

2. docs/dev/e2e_checklist.md (new, ~1500 lines)

The executable spec. Sections (best guess at row classes):

  • A: Customer enrollment (magic-link, identity persists, F5)
  • B: Support-agent enrollment (magic-link today; password-mode forward to v0.3)
  • C: Customer files first ticket (workspace pick, ticket.create, optimistic insert)
  • D: Customer–support real-time (presence, comments live, attachments inline)
  • E: Cross-project isolation
  • F: Image attachment lifecycle (paste, drag-drop, max-size, thumbnail render, /api/attachment/{id} download)
  • G: Modal flows (new ticket, project-config in _app)
  • H: Embedder contract (_app desktop mounts _ui_wasm::App; embed_smoke verifies; D-17 live-restart)
  • I: Configuration / branding (workspace name, user emails, phase13_seed.rs profiles, demo orchestrator)
  • J: Auth-split (forward to v0.3 — every row [skip: V03])
  • K: Operations (server boot, _ui dual-mode --dist, mycelium spawn, custom-protocol asset serve)
  • L: Programmable surface (every RPC method in openrpc.json + each MCP tool — analog of freezone's Section AA)
  • M: Visual regression (desktop-{empty,acme,detail,...} baselines + browser-screenshot baselines)

5-column schema. Per-row MS tag (v0.1 / v0.2 / v0.3 / v1.0). [skip: ...] markers. Audit log at the top mirrors freezone — every session adds an entry, every regression flips a column with strikethrough + reason.

3. docs/dev/architecture.md (new, ~400 lines)

Topology diagram (browser → _ui --dist → rpc.sock → _server → SQLite + events.sock → fanout → /ws/user/{id}). Networking layers. Failure tolerance. Component responsibilities (_server / _ui / _ui_wasm / _app / _sdk).

4. docs/dev/testing.md (new, ~300 lines) + 7-layer pyramid

Layer Tool What it catches Current Target v0.2 Target v1.0
1. Unit cargo test --lib Logic, types, RPC handlers 205 + 31 wasm same same
2. Smoke tests/smoke.sh (curl) Endpoints reachable, RPC routing 0 8 12
3. API integration existing integration.rs Wire-shape, permissions 74 (+3 L-03) same +5 same +15
4. E2E flow tests/e2e_journey.sh Full enrollment→ticket→comment 0 6 10
5. Playwright regression tests/playwright/*.spec.ts UI flows, multi-user real-time 0 12 25
6. Playwright adversarial same Wrong-role, double-submit, expired tokens 0 4 8
7. Visual hero_browser MCP + pixelmatch CSS, layout, dark theme 5 desktop manual + 9 SPA + 5 mobile

5. The 4-port browser-deployable demo as canonical test infra

The session-24 work (Mycelium + Hero rebrand on 8083-8086) becomes the canonical test environment. scripts/phase13_demo.sh --browser boots 2 _servers + 2 _ui --dist + 4 socat bridges; Playwright config picks them up via env vars; CI runs against the same recipe.

6. Decision file D-19-spec-as-checklist.md

Lock the freezone-pattern adoption: vision + executable spec + 7-layer pyramid as first-class artifacts. (Note: D-18 in this session was for spec-as-checklist; renumber on landing if needed.)

Out of scope (forward to other issues)

  • Implementing the Playwright suite — #3
  • Implementing auth-split — #4
  • Phase 16 visual polish — #2

Sequencing — Phase 18 (a/b/c)

  • Phase 18a: vision + executable-spec skeleton + sections A–D rows. Get the shape right. End-of-session: ~200-row checklist, ~30% green from existing tests. Reviewed by Specs.
  • Phase 18b: sections E–M rows + architecture.md + testing.md + 7-layer pyramid. End-of-session: ~500 rows, audit log live.
  • Phase 18c: Playwright suite landing (10–15 baseline scenarios) using the 4-port scheme. Wires the L5–L6 layer. Cross-references back into the checklist (every Playwright spec → row green).

Why now (sequencing rationale)

Phase 16b (visual polish) and #4 (auth-split) both want explicit acceptance criteria. The checklist gives them that. Phase 16b without the checklist = iterate on cosmetics with no clear "done" line. Auth-split without the checklist = land features without a security-row matrix to check against (freezone's "OWASP top-10 for auth" rows are the model).

Estimated effort

2-3 sessions

Success criterion

After Phase 18 lands, every issue in the project (open and closed) cross-references one or more checklist rows. Every PR description includes "rows green" / "rows changed". The checklist is the single page that answers "where is hero_assistance" for any stakeholder.

## Why We've built the engineering-discipline pieces of the multi-session pipeline (CLAUDE.md / prompt.md / decisions / limitations / sessions / kickstart / handoff / start / stop). What we're missing is the **product-spec** layer — a stakeholder-facing document that maps every user-facing behaviour to a verification across the test pyramid. The pattern this issue adopts: [`znzfreezone_deploy/docs/dev/e2e_checklist.md`](https://forge.ourworld.tf/znzfreezone_code/znzfreezone_deploy/src/branch/development/docs/dev/e2e_checklist.md) — 1860 lines, 30+ sections, ~600-row matrix, 5-column row state schema (Schema? / Wired? / MCP? / Browser? / Human?), audit-log at the top, stakeholder-first framing. Tracking issue [#86](https://forge.ourworld.tf/znzfreezone_code/home/issues/86) for context. **What makes this exemplary:** 1. Vision and checklist live in different files. Conflict-resolution rule: checklist wins (it's what ships); vision wins on future-tense statements. 2. Stakeholder-first framing — Management/Sales / Legal / Operations / Engineering / Partners get reading instructions; non-engineer can navigate. 3. Five-column row state replaces 3-column legacy. Maps 1:1 to the testing layers. `[skip: REASON]` mandatory for opt-out. 4. Audit log at the top is reverse-chronological; every ✅→❌ flip is recorded with reason. Self-correcting documentation. 5. Executive UX summary as narrative paragraphs (sections 1–13). Vision and verification stay in lockstep. 6. One-line summary: the elevator pitch. ## Goal Bring hero_assistance to "ship-ready" parity with the freezone documentation pattern. After this issue lands: - Every user action ("file a ticket", "see live presence", "paste an image") has a row in the checklist with a 5-column verification status - Every Phase 16+ deliverable references the rows it's making green - Every regression flips a column with strikethrough + reason — the audit trail is permanent - Non-engineer stakeholders can read the doc and know what works ## Deliverables ### 1. `docs/vision/HERO_ASSISTANCE.md` (new, ~600 lines) The freezone analog: *why* this product exists. - **Principles** (6-8): peer-to-peer (no central tracker), mycelium-bound (no public IPs), embed-as-Support-tab, schema-per-customer, AI-amenable (every action → MCP tool), config-as-code, "looks amazing" UI bar, no-rebuild-for-new-customer. - **Milestones**: v0.1 (backend complete, Phase 14 ✅), v0.2 (UI ready + Phase 16 polish), v0.3 (auth split — #4), v0.4 (E2E test suite — #3), v1.0 (one paying customer in production). - **Industry positioning**: Zendesk / Intercom / Linear customer portal. What we are; what we deliberately aren't. The "no central tracker" stance distinguishes us. - **Decisions index** — links to D-01..D-18, organized by topic. - **Future-tense section** — what's not v1 (cross-project federation, SSO, mobile native). ### 2. `docs/dev/e2e_checklist.md` (new, ~1500 lines) The executable spec. Sections (best guess at row classes): - **A:** Customer enrollment (magic-link, identity persists, F5) - **B:** Support-agent enrollment (magic-link today; password-mode forward to v0.3) - **C:** Customer files first ticket (workspace pick, ticket.create, optimistic insert) - **D:** Customer–support real-time (presence, comments live, attachments inline) - **E:** Cross-project isolation - **F:** Image attachment lifecycle (paste, drag-drop, max-size, thumbnail render, /api/attachment/{id} download) - **G:** Modal flows (new ticket, project-config in `_app`) - **H:** Embedder contract (`_app` desktop mounts `_ui_wasm::App`; embed_smoke verifies; D-17 live-restart) - **I:** Configuration / branding (workspace name, user emails, `phase13_seed.rs` profiles, demo orchestrator) - **J:** Auth-split (forward to v0.3 — every row `[skip: V03]`) - **K:** Operations (server boot, `_ui` dual-mode `--dist`, mycelium spawn, custom-protocol asset serve) - **L:** Programmable surface (every RPC method in openrpc.json + each MCP tool — analog of freezone's Section AA) - **M:** Visual regression (desktop-{empty,acme,detail,...} baselines + browser-screenshot baselines) 5-column schema. Per-row MS tag (v0.1 / v0.2 / v0.3 / v1.0). `[skip: ...]` markers. Audit log at the top mirrors freezone — every session adds an entry, every regression flips a column with strikethrough + reason. ### 3. `docs/dev/architecture.md` (new, ~400 lines) Topology diagram (browser → `_ui --dist` → rpc.sock → `_server` → SQLite + events.sock → fanout → /ws/user/{id}). Networking layers. Failure tolerance. Component responsibilities (`_server` / `_ui` / `_ui_wasm` / `_app` / `_sdk`). ### 4. `docs/dev/testing.md` (new, ~300 lines) + 7-layer pyramid | Layer | Tool | What it catches | Current | Target v0.2 | Target v1.0 | |---|---|---|---|---|---| | 1. Unit | `cargo test --lib` | Logic, types, RPC handlers | 205 + 31 wasm | same | same | | 2. Smoke | `tests/smoke.sh` (curl) | Endpoints reachable, RPC routing | 0 | 8 | 12 | | 3. API integration | existing `integration.rs` | Wire-shape, permissions | 74 (+3 L-03) | same +5 | same +15 | | 4. E2E flow | `tests/e2e_journey.sh` | Full enrollment→ticket→comment | 0 | 6 | 10 | | 5. Playwright regression | `tests/playwright/*.spec.ts` | UI flows, multi-user real-time | 0 | 12 | 25 | | 6. Playwright adversarial | same | Wrong-role, double-submit, expired tokens | 0 | 4 | 8 | | 7. Visual | hero_browser MCP + pixelmatch | CSS, layout, dark theme | 5 desktop manual | + 9 SPA | + 5 mobile | ### 5. The 4-port browser-deployable demo as canonical test infra The session-24 work (Mycelium + Hero rebrand on 8083-8086) becomes the canonical test environment. `scripts/phase13_demo.sh --browser` boots 2 `_server`s + 2 `_ui --dist` + 4 socat bridges; Playwright config picks them up via env vars; CI runs against the same recipe. ### 6. Decision file `D-19-spec-as-checklist.md` Lock the freezone-pattern adoption: vision + executable spec + 7-layer pyramid as first-class artifacts. (Note: D-18 in this session was for spec-as-checklist; renumber on landing if needed.) ## Out of scope (forward to other issues) - Implementing the Playwright suite — #3 - Implementing auth-split — #4 - Phase 16 visual polish — #2 ## Sequencing — Phase 18 (a/b/c) - **Phase 18a:** vision + executable-spec skeleton + sections A–D rows. Get the *shape* right. End-of-session: ~200-row checklist, ~30% green from existing tests. Reviewed by Specs. - **Phase 18b:** sections E–M rows + architecture.md + testing.md + 7-layer pyramid. End-of-session: ~500 rows, audit log live. - **Phase 18c:** Playwright suite landing (10–15 baseline scenarios) using the 4-port scheme. Wires the L5–L6 layer. Cross-references back into the checklist (every Playwright spec → row green). ## Why now (sequencing rationale) Phase 16b (visual polish) and #4 (auth-split) both want explicit acceptance criteria. The checklist gives them that. Phase 16b without the checklist = iterate on cosmetics with no clear "done" line. Auth-split without the checklist = land features without a security-row matrix to check against (freezone's "OWASP top-10 for auth" rows are the model). ## Estimated effort 2-3 sessions ## Success criterion After Phase 18 lands, every issue in the project (open and closed) cross-references one or more checklist rows. Every PR description includes "rows green" / "rows changed". The checklist is the single page that answers "where is hero_assistance" for any stakeholder.
mik-tf commented 2026-05-01 02:44:05 +00:00
Author
Owner
Copy link

Update (session 24): Issue #4 (originally "auth split / Phase 20" — same session) was closed as wrong scope. Phase 18's checklist Section J should document the three candidate v0.3.0+ auth paths as [skip: NO-CUSTOMER-DEMAND] rows so the analysis is preserved:

  1. Remember-me cookie (30-day signed JWT keyed on device_addr) — one-session feature when daily-magic-link papercut becomes real for someone
  2. Host-JWT delegation when embedded (Authorization: Bearer <host-jwt> validated against configurable JWKS) — per D-09 §"Argument" pt 5 the embed-as-Support-tab is the primary deployment; host shell auth flows through
  3. OIDC for standalone SPA (Okta / Google Workspace / Microsoft Entra) — well-trodden libraries; no password storage

Magic-link-for-everyone is the answer indefinitely per memory/feedback_no_auth_padding.md. Section J rows stay [skip: NO-CUSTOMER-DEMAND] until a real customer deployment surfaces a real gap, at which point a precise implementation issue gets filed.

**Update (session 24):** Issue #4 (originally "auth split / Phase 20" — same session) was closed as wrong scope. Phase 18's checklist Section J should document the three candidate v0.3.0+ auth paths as `[skip: NO-CUSTOMER-DEMAND]` rows so the analysis is preserved: 1. **Remember-me cookie** (30-day signed JWT keyed on `device_addr`) — one-session feature when daily-magic-link papercut becomes real for someone 2. **Host-JWT delegation when embedded** (`Authorization: Bearer <host-jwt>` validated against configurable JWKS) — per D-09 §"Argument" pt 5 the embed-as-Support-tab is the primary deployment; host shell auth flows through 3. **OIDC for standalone SPA** (Okta / Google Workspace / Microsoft Entra) — well-trodden libraries; no password storage Magic-link-for-everyone is the answer indefinitely per `memory/feedback_no_auth_padding.md`. Section J rows stay `[skip: NO-CUSTOMER-DEMAND]` until a real customer deployment surfaces a real gap, at which point a precise implementation issue gets filed.
mik-tf commented 2026-05-01 03:44:01 +00:00
Author
Owner
Copy link

Phase 18a complete — session 25 (commit 079f267 on development).

Two new docs landed

  • docs/vision/HERO_ASSISTANCE.md (230 lines) — mission, eight principles (peer-to-peer / mycelium-bound / embed-as-Support-tab / schema-per-customer / AI-amenable / config-as-code / "looks amazing" UI bar / auth-by-role-deferred), industry positioning vs Zendesk/Intercom/Linear, M1–M4 roadmap, 7-bucket decisions index covering D-01..D-18, conflict-resolution clause.
  • docs/dev/e2e_checklist.md (334 lines) — audit log (one s25 entry), Who-this-is-for 5-row table, Vision pull-in, 7-layer pyramid (current counts L1=236 / L2=0 / L3=74 / L4=0 / L5=0 / L6=0 / L7=5), 4-port browser-deployable access table, How-to-run blocks, M1–M4 milestone scope, 5-column row state schema (Schema?/Wired?/MCP?/Browser?/Human?), [skip: REASON] opt-out marker with recognised REASON list, sections A–D rows, process invariants block at bottom.

Sections A–D row counts

Section Rows Wired ✅ Human ✅ [skip: V03] [skip: M2]
A — Customer enrolment 25 12 1 0 0
B — Support-agent enrolment 5 1 0 3 0
C — Customer files first ticket 30 13 3 0 0
D — Customer-support real-time 30 15 6 0 2
Total 90 41 (~45%) 11 3 2

85 M1 + 5 M2 by milestone tag. Row IDs use M1-A-1 style (section letter + index) with M1=v0.1+v0.2 / M2=v0.3 / M3=v1.0 mapping at the top of the doc.

Process invariants adopted byte-for-byte from freezone

  1. Every Wired ✅ stamp points to a specific test_file:test_name reference in the row body.
  2. Every regression flips ✅ → strikethrough with reason in the audit log.
  3. [skip: REASON] markers must use the recognised REASON list.
  4. Sections are append-only by ID.
  5. Conflict-resolution rule: checklist wins on present-tense, vision wins on future-tense.
  6. Audit log is authoritative for the doc's own history.

What's deferred

  • Sections E–M → Phase 18b (next session). Section E (agent reply) / F (attachments) / G (multi-project) / H (_app chrome) / I (config) / J (auth-split candidates with [skip: V03]) / K (operations) / L (programmable surface, ~91 RPC rows) / M (visual baselines).
  • docs/dev/architecture.md + docs/dev/testing.md → Phase 18b.
  • Playwright suite (L5/L6 layers) → Phase 18c (= issue #3 first deliverable).

Test posture (unchanged from session 24)

  • Native: 205 passing / 3 L-03 unchanged / 1 phase10 transient flake / 9 ignored.
  • _ui_wasm lib: 31 passing unchanged.
  • Kickstart verify assertions: 261 → 273 (+12 doc-existence + grep assertions for the s25 docs).

Decisions / limitations

  • No new decisions filed. D-19 candidates (section ordering / row granularity) both held bias per §3 instruction (customer-first / per-behaviour). 18 locked decisions total: D-01..D-13 + D-15..D-18.
  • No new limitations. L-01..L-07 unchanged.
  • B.5 default-skip held per §3 ("docs only").

Phase B walk drifts (flagged at plan-proposal time, all reconciled)

  1. Freezone's actual FREEZONE.md embeds [D-NNN] refs inline rather than topic-indexing — followed §3's spec (topic-organised index across 7 buckets) since non-engineer stakeholders need that for navigation.
  2. §3's "150-200 rows" estimate was over-target — landed 90 rows (the honest user-observable inventory) because padding to 150 would be performative.

Phase 18b is next; 18c after that. v0.2.0 ships after Phase 18b + Phase 16b land.

**Phase 18a complete — session 25** (commit `079f267` on `development`). ## Two new docs landed - **`docs/vision/HERO_ASSISTANCE.md`** (230 lines) — mission, eight principles (peer-to-peer / mycelium-bound / embed-as-Support-tab / schema-per-customer / AI-amenable / config-as-code / "looks amazing" UI bar / auth-by-role-deferred), industry positioning vs Zendesk/Intercom/Linear, M1–M4 roadmap, 7-bucket decisions index covering D-01..D-18, conflict-resolution clause. - **`docs/dev/e2e_checklist.md`** (334 lines) — audit log (one s25 entry), Who-this-is-for 5-row table, Vision pull-in, 7-layer pyramid (current counts L1=236 / L2=0 / L3=74 / L4=0 / L5=0 / L6=0 / L7=5), 4-port browser-deployable access table, How-to-run blocks, M1–M4 milestone scope, 5-column row state schema (Schema?/Wired?/MCP?/Browser?/Human?), `[skip: REASON]` opt-out marker with recognised REASON list, sections A–D rows, process invariants block at bottom. ## Sections A–D row counts | Section | Rows | Wired ✅ | Human ✅ | `[skip: V03]` | `[skip: M2]` | |---|---|---|---|---|---| | A — Customer enrolment | 25 | 12 | 1 | 0 | 0 | | B — Support-agent enrolment | 5 | 1 | 0 | 3 | 0 | | C — Customer files first ticket | 30 | 13 | 3 | 0 | 0 | | D — Customer-support real-time | 30 | 15 | 6 | 0 | 2 | | **Total** | **90** | **41** (~45%) | **11** | **3** | **2** | 85 M1 + 5 M2 by milestone tag. Row IDs use `M1-A-1` style (section letter + index) with M1=v0.1+v0.2 / M2=v0.3 / M3=v1.0 mapping at the top of the doc. ## Process invariants adopted byte-for-byte from freezone 1. Every Wired ✅ stamp points to a specific `test_file:test_name` reference in the row body. 2. Every regression flips ✅ → ~~strikethrough~~ with reason in the audit log. 3. `[skip: REASON]` markers must use the recognised REASON list. 4. Sections are append-only by ID. 5. Conflict-resolution rule: checklist wins on present-tense, vision wins on future-tense. 6. Audit log is authoritative for the doc's own history. ## What's deferred - **Sections E–M** → Phase 18b (next session). Section E (agent reply) / F (attachments) / G (multi-project) / H (`_app` chrome) / I (config) / J (auth-split candidates with `[skip: V03]`) / K (operations) / L (programmable surface, ~91 RPC rows) / M (visual baselines). - **`docs/dev/architecture.md`** + **`docs/dev/testing.md`** → Phase 18b. - **Playwright suite (L5/L6 layers)** → Phase 18c (= issue #3 first deliverable). ## Test posture (unchanged from session 24) - Native: 205 passing / 3 L-03 unchanged / 1 phase10 transient flake / 9 ignored. - `_ui_wasm` lib: 31 passing unchanged. - Kickstart verify assertions: 261 → 273 (+12 doc-existence + grep assertions for the s25 docs). ## Decisions / limitations - **No new decisions filed.** D-19 candidates (section ordering / row granularity) both held bias per §3 instruction (customer-first / per-behaviour). 18 locked decisions total: D-01..D-13 + D-15..D-18. - **No new limitations.** L-01..L-07 unchanged. - **B.5 default-skip held** per §3 ("docs only"). ## Phase B walk drifts (flagged at plan-proposal time, all reconciled) 1. Freezone's actual `FREEZONE.md` embeds `[D-NNN]` refs inline rather than topic-indexing — followed §3's spec (topic-organised index across 7 buckets) since non-engineer stakeholders need that for navigation. 2. §3's "150-200 rows" estimate was over-target — landed 90 rows (the honest user-observable inventory) because padding to 150 would be performative. Phase 18b is next; 18c after that. v0.2.0 ships after Phase 18b + Phase 16b land.
mik-tf commented 2026-05-01 04:16:13 +00:00
Author
Owner
Copy link

Phase 18b — Done (session 26, commit 0c0abc3 on development)

Phase 18b shipped sections E–M rows (+225 rows / 74 wired-green / 21 human-stamps; doc-wide 90 → 315) plus two new companion docs (docs/dev/architecture.md ~350 lines + docs/dev/testing.md ~280 lines).

Per-section deltas

Section Topic Rows Wired ✅ Human ✅
E Support-agent reply on customer ticket 25 11 4
F Image attachments + drag-and-drop + paste 20 5 2
G Multi-project subscription 15 9 4
H _app desktop chrome 15 0 (Schema-only) 4
I Config persistence (D-17) 10 6 0
J Auth-split candidates (all [skip: V03]) 15 0 0
K Operations / runbook 20 8 2
L Programmable surface (one row per OpenRPC method) 91 26 0
M Visual baselines 14 9 askama-auto 5 manual desktop
Phase 18b totals 225 74 21

Doc-wide totals

  • 90 → 315 rows (sections A–M complete)
  • 33 → 107 wired-green (≈34% doc-wide; ≈69% applicable when Section L's 91 forward-deferred-test rows + Section J's 15 [skip: V03] rows are excluded)
  • 12 → 21 human-stamps (s23 walkthrough + s26 manual desktop captures)

Companion docs

  • docs/dev/architecture.md — ASCII topology diagram + 7-layer networking stack + failure tolerance + per-crate component responsibilities + cross-cutting concerns + open architectural gaps table
  • docs/dev/testing.md — 7-layer pyramid spec + file map + current vs target counts (real cargo test numbers: 236 L1+L3 passing; ~330 / ~444 v1 target) + per-layer how-to-run + what-it-catches/doesn't-catch + cross-link to checklist columns + authoring guide

No new decisions, no new limitations

All four D-19 candidates (Section L row format / Section M desktop baselines / architecture.md topology format / testing.md counts source) held bias per §3 instruction. B.5 default-skip held (docs only).

Test posture unchanged

205 native passing / 31 _ui_wasm lib passing / 3 L-03 unchanged / 1 phase10 transient flake / 8 ignored. Kickstart's verify assertions extended +24 (273 → 297).

Next

Phase 18 docs work is complete. Phase 16b (#2) and Phase 18c (#3) are now independent next-session candidates — 16b ships v0.2.0; 18c opens the test lane every Phase 19+ session needs.

## Phase 18b — Done (session 26, commit `0c0abc3` on `development`) Phase 18b shipped sections E–M rows (+225 rows / 74 wired-green / 21 human-stamps; doc-wide 90 → 315) plus two new companion docs (`docs/dev/architecture.md` ~350 lines + `docs/dev/testing.md` ~280 lines). ### Per-section deltas | Section | Topic | Rows | Wired ✅ | Human ✅ | |---|---|---|---|---| | E | Support-agent reply on customer ticket | 25 | 11 | 4 | | F | Image attachments + drag-and-drop + paste | 20 | 5 | 2 | | G | Multi-project subscription | 15 | 9 | 4 | | H | `_app` desktop chrome | 15 | 0 (Schema-only) | 4 | | I | Config persistence (D-17) | 10 | 6 | 0 | | J | Auth-split candidates (all `[skip: V03]`) | 15 | 0 | 0 | | K | Operations / runbook | 20 | 8 | 2 | | L | Programmable surface (one row per OpenRPC method) | 91 | 26 | 0 | | M | Visual baselines | 14 | 9 askama-auto | 5 manual desktop | | **Phase 18b totals** | | **225** | **74** | **21** | ### Doc-wide totals - 90 → **315 rows** (sections A–M complete) - 33 → **107 wired-green** (≈34% doc-wide; ≈69% applicable when Section L's 91 forward-deferred-test rows + Section J's 15 `[skip: V03]` rows are excluded) - 12 → **21 human-stamps** (s23 walkthrough + s26 manual desktop captures) ### Companion docs - `docs/dev/architecture.md` — ASCII topology diagram + 7-layer networking stack + failure tolerance + per-crate component responsibilities + cross-cutting concerns + open architectural gaps table - `docs/dev/testing.md` — 7-layer pyramid spec + file map + current vs target counts (real `cargo test` numbers: 236 L1+L3 passing; ~330 / ~444 v1 target) + per-layer how-to-run + what-it-catches/doesn't-catch + cross-link to checklist columns + authoring guide ### No new decisions, no new limitations All four D-19 candidates (Section L row format / Section M desktop baselines / architecture.md topology format / testing.md counts source) held bias per §3 instruction. B.5 default-skip held (docs only). ### Test posture unchanged 205 native passing / 31 `_ui_wasm` lib passing / 3 L-03 unchanged / 1 phase10 transient flake / 8 ignored. Kickstart's verify assertions extended +24 (273 → 297). ### Next Phase 18 docs work is complete. Phase 16b ([#2](https://forge.ourworld.tf/lhumina_code/hero_assistance/issues/2)) and Phase 18c ([#3](https://forge.ourworld.tf/lhumina_code/hero_assistance/issues/3)) are now independent next-session candidates — 16b ships v0.2.0; 18c opens the test lane every Phase 19+ session needs.
mik-tf commented 2026-05-03 16:27:45 +00:00
Author
Owner
Copy link

Phase 18 fully shipped end-to-end:

  • 18a (s25): vision doc docs/vision/HERO_ASSISTANCE.md + executable spec docs/dev/e2e_checklist.md skeleton + sections A–D rows. D-18 filed locking the freezone-pattern adoption.
  • 18b (s26): sections E–M rows (90 → 315) + docs/dev/architecture.md + docs/dev/testing.md (7-layer pyramid as first-class artefact).
  • 18c (s28): Playwright suite landed at the 4-port browser-deployable scheme. D-19 filed locking the test-substrate boundary (Playwright drives _ui --dist; hero_browser MCP owns L7 captures; _app desktop chrome and MultiProjectClient cross-mesh stay [skip: NO-AUTOMATED-DESKTOP]). +50 assertions across L2/L4/L5/L6.
  • 18c-release (s29): un-skipped 2 Playwright specs (enrol.spec.ts + breadcrumb.spec.ts) + 6 L7 SPA baselines via scripts/capture-spa-baselines.sh + 31 cell flips across Sections A/C/D/G/L. v0.3.0 tagged on development (commit 39d85e5).

All three sub-phases complete; D-18 + D-19 locked. Closing as shipped — should have closed in s29 alongside the v0.3.0 tag.

For per-phase historical detail, see prompt.md §1 and sessions/{25,26,28,29}.yml manifests.

Phase 18 fully shipped end-to-end: - **18a** (s25): vision doc `docs/vision/HERO_ASSISTANCE.md` + executable spec `docs/dev/e2e_checklist.md` skeleton + sections A–D rows. D-18 filed locking the freezone-pattern adoption. - **18b** (s26): sections E–M rows (90 → 315) + `docs/dev/architecture.md` + `docs/dev/testing.md` (7-layer pyramid as first-class artefact). - **18c** (s28): Playwright suite landed at the 4-port browser-deployable scheme. D-19 filed locking the test-substrate boundary (Playwright drives `_ui --dist`; `hero_browser` MCP owns L7 captures; `_app` desktop chrome and `MultiProjectClient` cross-mesh stay `[skip: NO-AUTOMATED-DESKTOP]`). +50 assertions across L2/L4/L5/L6. - **18c-release** (s29): un-skipped 2 Playwright specs (`enrol.spec.ts` + `breadcrumb.spec.ts`) + 6 L7 SPA baselines via `scripts/capture-spa-baselines.sh` + 31 cell flips across Sections A/C/D/G/L. **v0.3.0 tagged on `development`** (commit 39d85e5). All three sub-phases complete; D-18 + D-19 locked. Closing as shipped — should have closed in s29 alongside the v0.3.0 tag. For per-phase historical detail, see prompt.md §1 and sessions/{25,26,28,29}.yml manifests.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
v0.3.1
v0.2.2
v0.2.1
v0.2.0
v0.1.0
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_assistance#5
No description provided.