114 lines
6.4 KiB
Markdown
114 lines
6.4 KiB
Markdown
# 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.
|
|
- Keep `missioncore.laboratory-report/v1` executable: bounded `ENNResult.tsx`
|
|
modules supply all four `LaboratorySummary` brief fields and use
|
|
`LaboratoryResultSummary` for metrics plus proved/not-proved/decision. They
|
|
never own canonical summary/result markup. Anatomy changes require a new
|
|
version and product-owner agreement.
|
|
- 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.
|