chore(repo): codify local operator resource limits

2026-07-29 01:52:16 +03:00
parent d729abab31
commit bfd95c7fee
2 changed files with 58 additions and 7 deletions
@@ -30,6 +30,15 @@ the registries.
 - Keep the integrated Mission Core Control Station and API exclusively on
  `http://127.0.0.1:8000`.
 - Treat the canonical `8000` process as durable operator state, not as a
  disposable QA process. Finishing a test, build, browser check, Codex turn, or
  implementation increment never authorizes stopping it.
 - At the start of every Control Station task, inspect `8000`. If it is not
  serving Mission Core, start the canonical integrated service before UI work.
  At handoff, verify it again and leave it running.
 - A rebuild may replace the process on `8000`, but the replacement must be the
  same canonical service and must be listening successfully before handoff.
  Never leave the operator with a stopped Control Station after a restart.
 - Never start a second integrated backend on an alternate port to bypass a
  stale or occupied `8000`. In particular, TCP `8765` is a legacy Foxglove
  regression port and is not an operator path.
@@ -43,6 +52,30 @@ the registries.
  Mission Core backend on `8765`. Open or hand off `8000`, never an alternate
  backend URL.
 ## Local workstation resource gate
 - The local operator machine is a 14-inch 2023 MacBook Pro with only 18 GB of
  physical memory. Its memory, swap, CPU, GPU, and thermal headroom are part of
  the product-test safety boundary.
 - Run memory-intensive work sequentially. Never overlap a full frontend test
  pass, production build, Docker/Compose build or startup, synthetic replay,
  and browser visual QA.
 - Before starting a memory-intensive operation, inspect host memory pressure and
  the active Docker/process workload. If memory pressure is elevated or swap is
  growing, stop temporary work and recover headroom before continuing.
 - Prefer focused tests and an existing valid build. Run the full suite and
  production build only when they are required acceptance gates, one at a time.
 - Do not start Docker Desktop, Compose stacks, duplicate application servers,
  duplicate browser automation sessions, or load/stress tests for convenience.
  Bounded load work belongs on Worker 006, not on the Mac.
 - After each test, build, replay, or visual-QA stage, stop temporary watchers,
  publishers, viewers, workers, and containers before starting the next heavy
  stage. Preserve only the canonical integrated service on `8000` and other
  explicitly required durable operator services.
 - Do not change Docker Desktop CPU or memory limits without explicit product
  owner approval. A configured Docker VM ceiling is not safe available host
  memory.
 ## Component gate
 - Reuse package exports from `@nodedc/ui-react`, `@nodedc/ui-core`,
@@ -217,9 +250,11 @@ Before handoff:
 3. For a new surface, verify the product-surface brief names the user job,
   selected placement, rejected alternative, state grammar, and real acceptance
   evidence.
-4. Run `test/applicationArchitecture.test.mjs`, then the full frontend
+4. Under the local workstation resource gate, run
-   typecheck, unit tests, and production build.
+   `test/applicationArchitecture.test.mjs`, then the full frontend typecheck,
-5. Use the in-app browser to verify normal and expanded modes, every new view
+   unit tests, and production build sequentially. Never overlap these jobs.
 5. After the build/test processes have exited and memory headroom is confirmed,
   use the in-app browser to verify normal and expanded modes, every new view
   mode, keyboard Escape, and the canonical control states.
 6. Verify the default composition answers the primary operator question.
 7. Leave a real evidence case open for product-owner review.
@@ -26,17 +26,27 @@ and the boundary between Mission Core and vendor-specific integration code.
 ## Local operator resource envelope
- The operator Mac has 18 GB of physical memory. Treat local memory and swap as
+- The local operator machine is a 14-inch 2023 MacBook Pro with only 18 GB of
-  a hard shared limit, not as disposable build capacity.
+  physical memory. Treat local memory and swap as a hard shared operational
  limit, not as disposable build capacity.
 - Run frontend tests, production builds, Docker builds, runtime startup, and
  browser QA sequentially. Do not launch parallel heavy local jobs.
 - Do not start Docker Desktop, a Compose stack, a second browser automation
  session, or a full test/build pass merely for convenience. First prove that
  the operation is necessary, prefer the narrowest focused check, and keep no
  more than one memory-intensive validation job active at a time.
 - Do not run load or stress tests on the Mac. Run bounded synthetic load only on
  Worker 006, and remove every temporary process after the measurement.
 - Use only the canonical Mission Core endpoint on port `8000`; do not start
  duplicate application servers to work around stale state.
 - Before a memory-intensive local operation, inspect current memory pressure and
-  active Docker workload. Prefer focused tests and existing build artifacts when
+  active Docker workload. If memory pressure is elevated or swap is growing,
-  they are sufficient for acceptance.
+  stop and remove temporary jobs before continuing. Prefer focused tests and
  existing build artifacts when they are sufficient for acceptance.
 - After every local test, build, replay, browser-QA, or Docker operation, stop
  temporary workers, watchers, replay publishers, duplicate viewers, and
  containers that are not durable operator state. Keep only the canonical
  Mission Core service on `8000` and explicitly required operator services.
 - Docker Desktop's configured VM ceiling is not evidence that the host can
  safely supply that memory. Do not change Docker Desktop CPU or memory limits
  without explicit owner approval.
@@ -90,6 +100,12 @@ decoders before BLE/Wi-Fi/data-session evidence exists.
  port to bypass a stale process. TCP `8765` is legacy Foxglove regression
  only, not an operator path. Restart the canonical `8000` process and finish
  with no Mission Core backend listening on `8765`.
 - The canonical `8000` process is durable operator state. A completed test,
  build, browser QA pass, Codex turn, or implementation increment never
  authorizes stopping it. Every Control Station task starts by checking and, if
  necessary, starting the integrated service; every handoff verifies and leaves
  that exact service running on `8000`. A rebuild may replace it only when the
  replacement is confirmed listening before handoff.
 - `NODEDC_DESIGN_GUIDELINE` is the only visual-design source of truth. Before
  editing UI, read its `registry/registry.json`, `registry/components.json`,
  `registry/icons.json`, and the relevant component documentation.