Merge branch 'main' into develop

Author: jirhiker

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black

AGENTS.md

@@ -19,6 +19,35 @@ Pychron is a long-lived scientific application with mixed concerns:
 
 Favor conservative, low-regression changes over broad rewrites.
 
+Repo Map
+========
+
+Start with the user-facing subsystem and only expand outward as needed.
+
+- application/bootstrap and plugin wiring:
+  - `launchers/`
+  - `pychron/applications`
+  - `pychron/envisage`
+- experiment execution and scripting:
+  - `pychron/experiment`
+  - `pychron/pyscripts`
+- data reduction, processing, and pipeline work:
+  - `pychron/pipeline`
+  - `pychron/processing`
+- DVC and repository-backed persistence:
+  - `pychron/dvc`
+- hardware, instruments, and control surfaces:
+  - `pychron/hardware`
+  - `pychron/lasers`
+  - `pychron/extraction_line`
+  - `pychron/spectrometer`
+  - `pychron/furnace`
+- shared foundations used across many subsystems:
+  - `pychron/core`
+  - `pychron/database`
+  - `pychron/paths.py`
+  - `pychron/globals.py`
+
 Working Rules
 =============
 
@@ -28,28 +57,69 @@ Working Rules
 - Expect the repo to contain legacy modules, experimental files, and partial
   migrations; patch the active path you are changing instead of trying to
   normalize the whole tree in one pass.
+- If a subsystem repeatedly needs specialized guidance, add a nested
+  `AGENTS.md` in that directory instead of overloading the root file. Only do
+  this when the local conventions are stable and materially different from the
+  repo-wide defaults.
 
 Code Changes
 ============
 
 - Prefer focused edits over opportunistic refactors.
+- Add type annotations to any function you touch. If a full signature annotation
+  would force broader churn, annotate the parameters and return value needed for
+  the current edit and keep the rest of the change scoped.
+- When debugging a bug or regression, add targeted instrumentation early to
+  confirm control flow, state transitions, inputs, and external responses before
+  attempting speculative fixes.
 - When replacing debug `print()` calls in runtime code, use the repo's existing
   logging style:
   - `Loggable` subclasses use `self.debug(...)`, `self.warning(...)`, etc.
   - other modules typically use `new_logger(...)` or a local logger
+- Prefer narrow, hypothesis-driven instrumentation near the suspected failure
+  boundary first: UI actions, task/plugin entrypoints, hardware I/O, experiment
+  state changes, and DVC/database calls.
+- Remove temporary instrumentation before finishing unless it provides ongoing
+  operational value. Do not broaden a debugging task into repo-wide logging
+  cleanup or leave noisy logs in hot paths without justification.
 - Preserve `if __name__ == "__main__":` demo blocks unless the task is to remove
   them. Do not treat demo code as runtime code.
 - Keep imports modern in active Qt code. Avoid reintroducing `PySide`,
   `traitsui.qt4`, or `pyface.ui.qt4` in touched files.
 - Use ASCII unless the file already requires other characters.
 
+Triage Workflow
+===============
+
+- Identify the user-facing subsystem first, then trace inward to the smallest
+  active module that implements the behavior.
+- Check for nearby tests before editing. Prefer colocated tests under
+  `pychron/*/tests`, `test/`, or a subsystem-specific test package before
+  reaching for broad suites.
+- Favor the path already exercised by launchers, plugins, tasks, or currently
+  referenced docs. Do not normalize parallel legacy code paths unless the task
+  explicitly requires it.
+- Use documentation to disambiguate architecture, startup flow, or workflow
+  expectations, but do not widen the implementation scope just because related
+  docs exist.
+- When adding a nested `AGENTS.md`, keep it limited to local setup, testing,
+  or architectural traps. Do not duplicate root policies unless the local file
+  is intentionally narrowing them for that subtree.
+
 Testing
 =======
 
 - Run the narrowest useful verification for the files you touched.
 - Good default checks:
   - `python -m py_compile <files>`
   - `python -m unittest <module>`
+- Testing heuristics for this repo:
+  - prefer module-level or package-level checks before full-suite runs
+  - search for colocated tests under `pychron/*/tests` before using aggregate
+    runners such as `pychron/test_suite.py`
+  - if a change touches Qt, Traits, hardware, or external services, say what is
+    unavailable and fall back to source-level verification when runtime checks
+    are not feasible
 - If a subsystem depends on Qt, Traits, or hardware services that are unavailable,
   say so explicitly and fall back to source-level verification.
 
@@ -59,6 +129,11 @@ Docs And Workflow
 - Keep `README.md` high signal. It should explain what the repo is, where docs
   live, and how development works now.
 - Prefer documenting branch/release policy in `docs/dev_guide/`.
+- Useful orientation documents:
+  - `README.md`
+  - `docs/dev_guide/index.rst`
+  - `docs/dev_guide/running_pychron.rst`
+  - `docs/dev_guide/git_workflow.rst`
 - When release workflow changes, keep these files aligned:
   - `docs/dev_guide/git_workflow.rst`
   - `docs/dev_guide/repository_settings.rst`

architecture.md

@@ -0,0 +1,120 @@
+# Pychron Architecture
+
+## Purpose
+
+This file is a fast orientation guide for the active codebase. It is not a full
+design spec. Use it to find the right subsystem before making changes.
+
+## Top-Level Shape
+
+Pychron is a Qt desktop application built on Enthought Envisage and TraitsUI.
+The codebase combines:
+
+- application bootstrap and plugin composition
+- experiment execution and automation
+- DVC-backed persistence and repository workflows
+- hardware/instrument control
+- processing, plotting, and review tooling
+
+The active runtime package is `pychron/`. Legacy and experimental paths exist;
+prefer the path that is currently wired into launchers, tasks, and plugins.
+
+## Startup Flow
+
+The main startup path is:
+
+1. launcher script in `launchers/`
+2. launcher helper entry point
+3. environment/path/bootstrap setup
+4. `pychron.envisage.pychron_run`
+5. application object and plugin assembly
+6. Envisage task application run loop
+
+The runtime tree under `~/Pychron` is now bootstrap-managed. The supported
+operator and developer setup flow uses:
+
+- `pychron-bootstrap`
+- `pychron-doctor`
+- `python -m pychron doctor`
+
+See `docs/dev_guide/running_pychron.rst` and `docs/dev_guide/installation.rst`
+for the current startup and install flow.
+
+## Major Subsystems
+
+### Envisage / application shell
+
+- `pychron/envisage`
+- `pychron/applications`
+- `launchers/`
+
+Owns application startup, plugin registration, task panes, browser/task shell,
+preferences dialogs, and shared UI wiring.
+
+See `pychron/envisage/architecture.md`.
+
+### Experiment execution
+
+- `pychron/experiment`
+- `pychron/pyscripts`
+
+Owns experiment queues, execution state, automated runs, scripts, queue editors,
+and run lifecycle coordination.
+
+See `pychron/experiment/architecture.md`.
+
+### DVC persistence
+
+- `pychron/dvc`
+- parts of `pychron/entry`, `pychron/loading`, `pychron/data_mapper`
+
+Owns repository-backed persistence, metadata lookup, analysis save/pull/push
+behavior, and DVC-facing import/export helpers.
+
+See `pychron/dvc/architecture.md`.
+
+### Hardware and instruments
+
+- `pychron/hardware`
+- `pychron/extraction_line`
+- `pychron/lasers`
+- `pychron/spectrometer`
+- `pychron/furnace`
+
+Owns device managers, controllers, remote hardware integration, and task-level
+instrument UIs.
+
+See `pychron/hardware/architecture.md`.
+
+### Processing and review
+
+- `pychron/pipeline`
+- `pychron/processing`
+- `pychron/envisage/browser`
+
+Owns data reduction, browser tables, plotting, review tools, and many operator
+analysis workflows.
+
+## Shared Foundations
+
+Common cross-cutting infrastructure lives in:
+
+- `pychron/core`
+- `pychron/database`
+- `pychron/paths.py`
+- `pychron/globals.py`
+
+Treat these as shared dependencies. Changes here have a larger blast radius than
+changes inside a task-specific package.
+
+## Working Guidance
+
+- Trace from the user-visible screen or command first, then narrow to the active
+  plugin, task, manager, or editor.
+- Check for local `architecture.md` and `AGENTS.md` files before changing a deep
+  subsystem.
+- Add instrumentation early when debugging cross-subsystem behavior, especially
+  at plugin boundaries, queue execution boundaries, hardware I/O, and DVC save
+  or load points.
+- Prefer small fixes in the active path over broad cleanup across parallel
+  legacy implementations.