Repository operating rules

NODEDC MISSION CORE is a vendor-neutral mission-control monorepo. Its first real device plugin investigates an owner-controlled XGRIDS/LixelKity K1 as a black-box sensor. Preserve the device, the host, the working LAN, raw evidence, and the boundary between Mission Core and vendor-specific integration code.

Non-negotiable safety boundaries

Default to non-mutating discovery or read-only operations. CoreBluetooth BLE scanning on macOS is active discovery, not passive radio sniffing.
Do not send BLE writes until the exact service, characteristic, framing, payload semantics, rollback, and expected state transition are documented.
BLE notification subscription may perform the standard temporary CCCD write; disclose it explicitly and do not conflate it with provisioning writes.
Do not fuzz, brute-force, upload firmware, delete device files, guess SSH/ADB credentials, or probe unrelated LAN devices.
Network probes must target the confirmed K1 IP. A full home-subnet scan is not a default operation.
Never place a Wi-Fi password in CLI arguments, logs, manifests, source, test fixtures, or Git history.
Do not install Python packages globally. Use the repository-local .venv managed by uv.
Do not install or alter Homebrew/system components unless the user explicitly authorizes that concrete change.

Evidence rules

Reference inputs under docs/reference/ are immutable; write corrections in audits or ADRs.
Every real experiment gets a session ID, UTC and monotonic timestamps, a redacted manifest, operator notes, and SHA-256 hashes for raw artifacts.
Real PCAP, K1 projects, logs, images, point clouds, credentials, serials, and router client lists stay out of normal Git. Git LFS solves size, not secrecy.
Synthetic or explicitly redacted fixtures may be committed under tests/fixtures/.

Implementation order

Follow the gates in docs/01_IMPLEMENTATION_PLAN.md. Do not build heavy decoders before BLE/Wi-Fi/data-session evidence exists.

Product UI governance

For every Control Station, LAB, viewer, or product-presentation change, use .codex/skills/mission-core-product-ui/SKILL.md and follow docs/17_PRODUCT_UI_AND_LAB_PRESENTATION_CANON.md and docs/18_APPLICATION_COMPONENT_ARCHITECTURE.md.
The integrated Control Station and API have one canonical local endpoint: http://127.0.0.1:8000. Never start a second Mission Core backend on another 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.
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.
Reuse @nodedc/ui-react, @nodedc/ui-core, tokens, icons, and page patterns. Do not create an application-local visual control, interaction state, geometry, color language, or copy of a design-system component.
If the required visual entity is absent from the Design Guideline, stop and obtain explicit product-owner approval. After approval, add it to the Design Guideline first with registry, documentation, states, and validation; only then consume it here.
Domain renderers may remain Mission Core code when they visualize Mission Core data. Their controls and containing surfaces must still be composed from canonical Design Guideline exports.
Product UI must not expose implementation steps, roadmap gates, internal reason taxonomies, debug controls, placeholder status blocks, or temporary experiment scaffolding. Keep these in Ops, engineering reports, or developer tooling.
Extend one reusable application pattern instead of adding per-LAB layouts. A new LAB supplies data and renderer configuration; it does not invent a new page hierarchy or visual language.
Do not generalize the LAB hierarchy into a universal application template. For a new non-LAB interface, follow docs/19_PRODUCT_SURFACE_EXTENSION_PROTOCOL.md: identify the operator job, compare placement/composition alternatives, classify the novelty, and obtain product-owner agreement before adding a workspace, changing primary navigation, or introducing a new product root.
Preserve one product grammar while allowing task-specific composition. A scene, map, timeline, queue, editor, topology, dashboard, and LAB review may have different layouts when their entity, lifecycle, or action model differs.
Preserve the internal dependency direction: core → components/renderers → workspaces → composition/App. Core never imports workspaces or visual adapters; reusable components never import workspaces. New domains and LAB runs get their own feature module instead of growing App.tsx, Workspaces.tsx, or generic CSS buckets.
Treat productModel.ts, executable versioned contracts, and the experimental vocabulary as the current local semantic sources. Do not add a parallel runtime ontology unless the admission conditions in docs/18_APPLICATION_COMPONENT_ARCHITECTURE.md are met.

Laboratory presentation and reporting

Use one fixed laboratory presentation contract: selectors, one compact canonical summary, admitted evidence viewer(s), result, and optional reusable technical details.
The compact summary must explain the decision question, immutable source, tested method/models/algorithms, experimental mode, principal result, limitations, and retained authority. It is not the engineering report.
The complete engineering report belongs in the Mission Core Ops card as titled structured blocks: objective and architecture stage, source evidence, method/models/algorithms, worker/runtime, implementation, validation, results, regressions and limitations, decision, next stage, and acceptance checker.
Spatial evidence uses 3D by default. Image-space reprojection may be offered as a 2D diagnostic mode inside the same reusable viewer. Primary evidence viewers must provide the canonical expand/restore action.

6.1 KiB Raw Blame History