Add developer methodology guides and project coder lexicon

Author: RhodosBerger

advanced_cnc_copilot/FEATURE_IMPLEMENTATION_BLUEPRINT.md

@@ -171,3 +171,9 @@ This blueprint follows documentation conventions commonly used in mature industr
 - **Lifecycle clarity**: includes implementation sequence, DoD, and immediate actions.
 
 For low-level operational and contract details, see `docs/TECHNICAL_REFERENCE.md`.
+
+Contributor workflow docs:
+- `docs/DEVELOPER_EDITING_GUIDE.md`
+- `docs/METHODOLOGY_OF_ANALOGY.md`
+- `docs/CODER_LEXICON.md`
+

advanced_cnc_copilot/README.md

@@ -146,6 +146,9 @@ A three-agent system ensuring safe AI integration:
 - `SYSTEM_ARCHITECTURE.md`: architecture and data-flow map.
 - `FEATURE_IMPLEMENTATION_BLUEPRINT.md`: roadmap-driven delivery blueprint.
 - `docs/TECHNICAL_REFERENCE.md`: production-style technical contracts, NFRs, safety and release criteria.
+- `docs/DEVELOPER_EDITING_GUIDE.md`: safe code editing workflow and PR checklist.
+- `docs/METHODOLOGY_OF_ANALOGY.md`: analogy methodics and validation protocol.
+- `docs/CODER_LEXICON.md`: canonical project vocabulary for consistent implementation language.
 
 ## Delivery Blueprint (Roadmap -> Execution)
 

advanced_cnc_copilot/docs/CODER_LEXICON.md

@@ -0,0 +1,89 @@
+# Coder Lexicon
+
+A shared vocabulary for contributors. Use these terms consistently in code, docs, and PRs.
+
+## A
+
+- **Action Trace**: Ordered list of actions proposed/applied during a scenario.
+- **Auditor Verdict**: Deterministic pass/fail decision on a proposed action set.
+
+## B
+
+- **Blueprint Track**: A feature workstream in `FEATURE_IMPLEMENTATION_BLUEPRINT.md`.
+- **Boundary Validation**: Input normalization and schema checks at API/WS edges.
+
+## C
+
+- **Creator**: Agent that proposes strategies or mutations.
+- **Contract Field**: A payload field with defined semantics and compatibility expectations.
+
+## D
+
+- **Decision Packet**: Structured unit containing proposal, scores, and reasoned decision.
+- **Deterministic Safety Gate**: Hard constraint layer that blocks unsafe actions.
+
+## E
+
+- **Execution Plane**: HAL/hardware/simulator domain where commands become physical effects.
+
+## F
+
+- **Fallback Stream**: Global websocket stream (`/ws/telemetry`) used if machine-scoped stream is unavailable.
+
+## H
+
+- **HAL**: Hardware Abstraction Layer connecting software to CNC hardware/simulator.
+- **Hub**: Dashboard entry view linking operational and fleet pages.
+
+## I
+
+- **Interface Layer**: HTTP/WebSocket layer; translation only, minimal logic.
+
+## L
+
+- **Lexicon Term**: Canonical project term expected to remain stable across docs.
+
+## M
+
+- **Machine-Scoped Stream**: WebSocket endpoint `/ws/telemetry/{machine_id}`.
+- **Methodics**: Repeatable procedural method for implementing or validating a concept.
+
+## N
+
+- **NFR**: Non-Functional Requirement (reliability, performance, security, observability).
+
+## O
+
+- **Operational Readiness**: State where monitoring, safety, and runbook criteria are met.
+
+## P
+
+- **Preference Pair**: LLM training sample comparing good vs bad plan.
+- **Primary Path**: Preferred runtime path before fallback logic.
+
+## R
+
+- **Reason Code**: Machine-readable explanation for pass/fail/block decisions.
+- **Rollback Trigger**: Condition requiring reversion to safer prior behavior.
+
+## S
+
+- **Shadow Mode**: Recommendation-only deployment with no autonomous execution.
+- **Shadow Council**: Creator + Auditor + Accountant decision framework.
+
+## T
+
+- **Telemetry Window**: Time-series slice used for decision and training.
+- **Traceability Crosswalk**: Mapping from roadmap source docs to implementation tracks.
+
+## U
+
+- **Upgrade Safety**: Principle of additive/compatible changes in contracts.
+
+## V
+
+- **Validation Gate**: Any explicit checkpoint that must pass before progression.
+
+## W
+
+- **Workstream**: Cohesive implementation track with acceptance criteria.

advanced_cnc_copilot/docs/DEVELOPER_EDITING_GUIDE.md

@@ -0,0 +1,76 @@
+# Developer Editing Guide
+
+This guide explains **how to safely edit code in FANUC RISE** while preserving architecture, safety, and documentation standards.
+
+## 1) Working Agreement (before editing)
+
+1. Identify the layer you are touching:
+   - **Repository/Data layer**: storage access only.
+   - **Service layer**: business logic and domain rules.
+   - **Interface layer**: HTTP/WebSocket translation only.
+   - **HAL layer**: hardware/simulator interaction.
+2. Keep changes scoped to one concern per commit.
+3. If behavior changes, update documentation in the same PR.
+4. Safety logic must remain deterministic and explicit.
+
+## 2) Standard Edit Workflow
+
+### Step 1 — Locate ownership
+- Confirm which module owns behavior before changing anything.
+- Avoid adding logic to transport/controller files when it belongs in services.
+
+### Step 2 — Make minimal delta
+- Prefer focused edits over broad refactors.
+- Preserve public contracts unless explicitly versioning them.
+
+### Step 3 — Validate locally
+- Syntax check changed language files.
+- Run basic smoke checks for impacted entrypoints.
+- Verify machine-scoped and fallback telemetry paths if touching dashboard/ws code.
+
+### Step 4 — Document and annotate
+- Update one of:
+  - `README.md` (entry-level impact)
+  - `SYSTEM_ARCHITECTURE.md` (flow/architecture impact)
+  - `docs/TECHNICAL_REFERENCE.md` (contract/NFR impact)
+
+## 3) Editing Rules by Layer
+
+### Interface Layer (FastAPI/WS/UI)
+- Keep handlers thin; no hidden business rules.
+- Validate and normalize inputs at boundaries.
+- Include reason codes for safety-relevant outcomes.
+
+### Service Layer
+- Keep deterministic policy checks explicit and testable.
+- Separate AI proposal generation from safety decision logic.
+
+### HAL Layer
+- Use circuit breakers and bounded retries.
+- Always provide simulator fallback path for non-hardware environments.
+
+### Data Layer
+- Keep schema evolution backward-compatible where possible.
+- Prefer additive migration strategy for minor versions.
+
+## 4) Pull Request Checklist for Editors
+
+- [ ] Change is scoped and explained.
+- [ ] Contracts impacted are documented.
+- [ ] Safety model unchanged or explicitly strengthened.
+- [ ] Bootstrap/runbook instructions still valid.
+- [ ] Feature blueprint or roadmap mapping updated (if relevant).
+
+## 5) Anti-Patterns to Avoid
+
+- Embedding domain logic in route/controller files.
+- Treating LLM confidence as a safety gate.
+- Adding hardcoded hostnames/ports where runtime-derived config is needed.
+- Changing websocket payload shape without documenting compatibility implications.
+
+## 6) Recommended Commit Style
+
+Use intent-first commit messages:
+- `harden ws fallback for machine-scoped telemetry`
+- `document api reason_code contract for auditor decisions`
+- `refactor service-layer policy checks into deterministic validator`

advanced_cnc_copilot/docs/METHODOLOGY_OF_ANALOGY.md

@@ -0,0 +1,66 @@
+# Methodology of Analogy
+
+This project uses analogy as a **design reasoning method** (not as proof). The goal is to convert complex systems into understandable engineering decisions while keeping validation deterministic.
+
+## 1) Why analogy is used
+
+Manufacturing intelligence spans hardware, data systems, and decision engines. Analogy helps teams:
+- communicate intent across disciplines,
+- reason about architecture boundaries,
+- teach concepts quickly,
+- preserve a shared mental model.
+
+## 2) Core rule: Analogy guides design, metrics validate design
+
+- Analogy can propose a model.
+- Tests, telemetry, and safety constraints accept or reject the model.
+
+## 3) Reusable analogy patterns in this repo
+
+### A) Nervous System Analogy
+- Interface layer = sensory nerves.
+- Service layer = brain processing.
+- HAL = motor/physical actuation.
+- Use when deciding where logic belongs.
+
+### B) Shadow Council Analogy
+- Creator = proposal engine.
+- Auditor = deterministic law.
+- Accountant = trade-off scorer.
+- Use when implementing safe AI workflow.
+
+### C) Economic Translation Analogy
+- SaaS metrics (churn/CAC) mapped to manufacturing costs/risks.
+- Use for optimization and reporting semantics.
+
+## 4) Analogy-to-Implementation Protocol
+
+1. **Name the analogy** (e.g., "nervous system").
+2. **Map entities to concrete modules**.
+3. **Define constraints that cannot be violated**.
+4. **Define measurable outcomes**.
+5. **Run simulation or controlled validation**.
+6. **Accept/reject based on evidence**.
+
+## 5) Failure modes and mitigations
+
+- **Failure mode**: treating metaphor as implementation detail.
+  - **Mitigation**: maintain explicit contracts and tests.
+- **Failure mode**: analogy drift across teams.
+  - **Mitigation**: use shared lexicon and architecture docs.
+- **Failure mode**: narrative over safety.
+  - **Mitigation**: deterministic policy layer always precedes execution.
+
+## 6) Example conversion template
+
+Use this template when introducing a new analogy:
+
+- Analogy name:
+- Problem it clarifies:
+- Module mapping:
+- Hard constraints:
+- Success metrics:
+- Validation plan:
+- Rollback criteria:
+
+This keeps analogy usage operational, measurable, and safe.