DockLayouts has an unusually deep evidence surface: pure model units, component fixtures, headed whitebox E2E, Neural Link worker/main inspection, rendered theme checks, mutation controls, and external-Brain runtime gates. The generic testing guides cannot encode the subsystem-specific evidence boundaries.
The Problem
Maintainers repeatedly get green-looking wrong answers by sampling the wrong plane, using stale theme output, skipping the external runtime gate, observing live DOM instead of VDOM ownership, or treating a test tally as failure disposition. There is no guide explaining how to choose an instrument that can contain the DockLayouts answer.
The Architectural Reality
The current suite spans test/playwright/{unit,component,e2e}/dashboard, Workstation whitebox journeys, theme fixtures, and Neural Link. Model truth, App-worker component truth, VDOM delivery, painted DOM, and physical windows are distinct observation surfaces; custom Playwright configs and headed execution are mandatory for different questions.
The Fix
Create learn/guides/testing/DockLayoutsTesting.md: an evidence-first guide to reproducing, observing, mutating, and debugging DockLayouts across its model, worker, DOM, and window planes.
Contract Ledger
Target Surface
Source of Authority
Proposed Behavior
Fallback
Docs
Evidence
Testing guide
Current DockLayouts unit/component/E2E suites + Neural Link
Teach instrument choice by authority plane and failure class
Re-census suite at pickup
New guide
Red-first and mutation receipts
Runtime gates
Current Playwright configs + external Brain root behavior
Explain when a listed test is actually discoverable/executable
Fail closed on missing runtime
Same guide
List/run controls
Registration
Existing testing-guide siblings
One discoverable Testing guide
No generated-output edits
tree + SEO inputs
lint + rendered portal
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains evidence collection.
Acceptance Criteria
The guide clears the full guide-authoring bar: source/tool-grounded narrative, reader-owned benefits, lived maintainer voice, and at least one render-verified flowchart TD.
The guide separates explanation from reference: no inlined API/schema/test catalog, and no ticket or PR ids in guide prose.
The new source guide is registered in learn/tree.json and the SEO PRIORITIES input; generated sitemap/LLM outputs remain untouched.
Current-source consistency, guide lint, tree lint, portal rendering, and an independent cross-family whole-guide review are recorded in the PR.
The guide maps model, App worker, VDOM, DOM/paint, main-thread geometry, and physical-window questions to instruments that can observe them.
It uses current custom unit/component/E2E configurations and demonstrates at least one red-first reproduction plus a mutation control.
It explains external-Brain runtime discovery, headed requirements, theme freshness, deterministic versus batch-order failures, and privacy-safe diagnostics.
It links generic testing and Neural Link references instead of copying commands or tool catalogs.
Out of Scope
A full test inventory, CI redesign, or fixing current DockLayouts defects.
Avoided Traps
Do not run default Playwright, claim zero tests as green, use fixed sleeps as semantic evidence, or collapse worker truth and painted DOM into one plane.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Retrieval Hint: query_raw_memories("DockLayouts guide series post-refactor final API")
Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.
Context
DockLayouts has an unusually deep evidence surface: pure model units, component fixtures, headed whitebox E2E, Neural Link worker/main inspection, rendered theme checks, mutation controls, and external-Brain runtime gates. The generic testing guides cannot encode the subsystem-specific evidence boundaries.
The Problem
Maintainers repeatedly get green-looking wrong answers by sampling the wrong plane, using stale theme output, skipping the external runtime gate, observing live DOM instead of VDOM ownership, or treating a test tally as failure disposition. There is no guide explaining how to choose an instrument that can contain the DockLayouts answer.
The Architectural Reality
The current suite spans
test/playwright/{unit,component,e2e}/dashboard, Workstation whitebox journeys, theme fixtures, and Neural Link. Model truth, App-worker component truth, VDOM delivery, painted DOM, and physical windows are distinct observation surfaces; custom Playwright configs and headed execution are mandatory for different questions.The Fix
Create
learn/guides/testing/DockLayoutsTesting.md: an evidence-first guide to reproducing, observing, mutating, and debugging DockLayouts across its model, worker, DOM, and window planes.Contract Ledger
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains evidence collection.
Acceptance Criteria
flowchart TD.learn/tree.jsonand the SEOPRIORITIESinput; generated sitemap/LLM outputs remain untouched.Out of Scope
A full test inventory, CI redesign, or fixing current DockLayouts defects.
Avoided Traps
Do not run default Playwright, claim zero tests as green, use fixed sleeps as semantic evidence, or collapse worker truth and painted DOM into one plane.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Origin Session ID: 309a78d7-2d95-4f23-bdfc-69d2ae393a5d
Retrieval Hint:
query_raw_memories("DockLayouts guide series post-refactor final API")Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.