Add dependency bootstrap audit script and roadmap execution blueprint

advanced_cnc_copilot/FEATURE_IMPLEMENTATION_BLUEPRINT.md

@@ -0,0 +1,179 @@
+# FANUC RISE Feature Implementation Blueprint
+
+This document turns the project roadmaps into an executable delivery plan. It is meant to be used with:
+- `ROADMAP_TO_ARCHITECTURE.md`
+- `IMPLEMENTATION_STRATEGY_PHASE2.md`
+- `cms/theories/PROJECT_STATE_AND_ROADMAP.md`
+- `NEXT_STEPS_OVERVIEW.md`
+
+## 0) Roadmap Source Crosswalk (MD -> Implementation)
+
+| Source document | What it contributes | Implemented as track |
+|---|---|---|
+| `ROADMAP_TO_ARCHITECTURE.md` | Macro architecture phases and target platform shape | A, B, E |
+| `IMPLEMENTATION_STRATEGY_PHASE2.md` | Mid-phase delivery and integration sequencing | B, C, D |
+| `cms/theories/PROJECT_STATE_AND_ROADMAP.md` | Current-state inventory + quarterly objectives | A, C, E |
+| `NEXT_STEPS_OVERVIEW.md` | Tactical next actions and commercialization flow | C, D, E |
+
+This crosswalk exists so every roadmap statement is traceable to an engineering workstream.
+
+## 1) Dependency Baseline (must pass first)
+
+### Required runtime layers
+1. **Python backend** (FastAPI + orchestration + simulator/HAL)
+2. **Database** (PostgreSQL / TimescaleDB)
+3. **Optional cache/bus** (Redis)
+4. **Frontend clients** (React / Vue / dashboard HTML)
+
+### One-command bootstrap
+Use:
+```bash
+./tools/bootstrap_and_audit.sh
+```
+
+The script creates `.venv`, installs Python deps, installs Node deps in all frontend workspaces, and prints npm/pip diagnostics.
+
+---
+
+## 2) Feature Delivery Tracks (from MD roadmaps)
+
+## Track A — Hardware + HAL Reliability
+**Goal**: production-safe telemetry and command path.
+
+### A1. FOCAS bridge hardening
+- Implement circuit breaker retries + timeout budgets in HAL adapters.
+- Add machine profile registry (`Fanuc`, `Siemens`, `Mock`) to avoid hardcoded assumptions.
+- Acceptance:
+  - Graceful degradation to simulator when hardware unavailable.
+  - 0 unhandled exceptions on adapter disconnect/reconnect chaos test.
+
+### A2. Latency pipeline
+- Move high-frequency shared state to Redis streams or Arrow IPC.
+- Add p50/p95/p99 telemetry pipeline timing metrics.
+- Acceptance:
+  - p95 ingestion-to-dashboard < 100ms in simulator load tests.
+
+## Track B — Shadow Council Safety Governance
+**Goal**: AI suggestions never bypass deterministic guardrails.
+
+### B1. Auditor policy engine
+- Encode hard constraints for load/vibration/thermal/curvature bounds.
+- Expose policy decisions + reasoning traces over API.
+- Acceptance:
+  - Any violating proposal is blocked with explicit reasons.
+
+### B2. Creator + Accountant integration
+- Creator generates strategy candidates.
+- Accountant scores economics/time/risk.
+- Auditor performs final deterministic gate.
+- Acceptance:
+  - Decision packet contains proposal, economics score, and pass/fail rationale.
+
+## Track C — Probability Canvas + Fleet UX
+**Goal**: roadmap-aligned multi-machine operations.
+
+### C1. Fleet switching
+- Keep machine-specific websocket route as primary (`/ws/telemetry/{machine_id}`) with fallback.
+- Add machine selector and persisted last-machine state.
+- Acceptance:
+  - Operator can switch among 3+ machines without page refresh.
+
+### C2. Fleet health overview
+- Add hub-level card metrics (status, load trend, alert count) per machine.
+- Acceptance:
+  - Hub view updates in near real-time and highlights critical nodes.
+
+## Track D — Simulator-to-LLM Training Loop
+**Goal**: improve model quality safely offline.
+
+### D1. Scenario generation service
+- Generate normal + fault scenarios (chatter, thermal drift, stall).
+- Persist traces in consistent schema.
+
+### D2. Dataset builder
+- Build SFT examples and pairwise preference data.
+- Include auditor verdicts and economics outcomes.
+
+### D3. Shadow deployment gate
+- Model can propose only; deterministic systems decide execution.
+- Acceptance:
+  - Safety violation rate and rejection rate dashboards available.
+
+## Track E — Multi-site Cloud + ERP Integration
+**Goal**: roadmap Q2/Q3 scalability.
+
+### E1. Fleet registry + tenancy
+- Add site and machine tenancy boundaries.
+- Implement RBAC scoped by site/role.
+
+### E2. Event-driven sync
+- Broadcast relevant learnings across machines (with policy controls).
+- Acceptance:
+  - Cross-machine strategy propagation with audit trail.
+
+---
+
+## 3) Suggested Sprint Plan (12-week template)
+
+### Sprint 1-2
+- Dependency baseline, CI checks, API health hardening.
+- Deliverables: repeatable local bootstrap, passing lints/checks.
+
+### Sprint 3-4
+- HAL resiliency + telemetry latency instrumentation.
+- Deliverables: circuit breaker + latency dashboard.
+
+### Sprint 5-6
+- Shadow Council decision packet + deterministic policy traceability.
+- Deliverables: pass/fail auditor API with reason codes.
+
+### Sprint 7-8
+- Fleet UX (machine selector, hub rollup metrics, alerts).
+- Deliverables: live multi-node dashboard.
+
+### Sprint 9-10
+- Simulator scenario generation + dataset pipeline.
+- Deliverables: exportable SFT/preference datasets.
+
+### Sprint 11-12
+- Shadow deployment and go/no-go gates for pilot.
+- Deliverables: pilot checklist + rollback plan.
+
+---
+
+## 4) Engineering Definition of Done
+
+A feature is done only if all conditions hold:
+1. Unit/integration checks pass.
+2. Feature has monitoring signals (health, latency, error rate).
+3. Auditor safety constraints are applied where relevant.
+4. Docs updated (README + architecture + API notes).
+5. Simulator regression scenarios pass.
+
+---
+
+## 5) Immediate next actions
+
+1. Run `./tools/bootstrap_and_audit.sh`.
+2. Bring up backend and verify `/api/health` and websocket routes.
+3. Implement Fleet selector persistence in dashboard UI.
+4. Add Auditor reason-code schema and include in websocket payload.
+5. Create simulator dataset export command for SFT + preference data.
+
+
+## 6) Documentation Standards Used
+
+This blueprint follows documentation conventions commonly used in mature industrial software projects:
+- **Traceability**: each workstream references roadmap sources.
+- **Acceptance criteria**: every feature track has measurable outcomes.
+- **Operational readiness**: runability and fallback behavior are first-class requirements.
+- **Safety by design**: deterministic controls are explicit and mandatory.
+- **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

@@ -139,6 +139,112 @@ A three-agent system ensuring safe AI integration:
 - Interface topology approach for connecting disparate systems
 - Nightmare Training for offline learning through simulation
 
+
+## Documentation Set (Complete)
+
+- `README.md`: project entrypoint, setup, and quickstart.
+- `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.
+- `docs/COMPONENT_COMPLETION_REPORT.md`: evidence-based status of what is done vs in progress.
+- `docs/NEXT_WEEK_DEVELOPMENT_PLAN.md`: concrete next-week implementation commitments.
+- `docs/MONETIZATION_ARTICLE_PRODUCTIZED_AI_CNC.md`: monetization strategy for product tiers and outcome-based pricing.
+- `docs/MONETIZATION_ARTICLE_SERVICES_AND_ECOSYSTEM.md`: services/ecosystem-led commercialization strategy.
+
+## Delivery Blueprint (Roadmap -> Execution)
+
+- **Feature execution plan**: `FEATURE_IMPLEMENTATION_BLUEPRINT.md` (maps roadmap docs into tracks, sprints, DoD, and acceptance criteria).
+- **Bootstrap + dependency audit script**: `tools/bootstrap_and_audit.sh` (creates Python env, installs dependencies across workspaces, runs quick diagnostics).
+
+## Dependency Bootstrap & Environment Debugging
+
+To avoid mixed environments, use one Python environment and install frontend dependencies per app folder.
+
+### 1) Python backend environment
+```bash
+cd advanced_cnc_copilot
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -r flask_service/requirements.txt
+```
+
+If you prefer conda:
+```bash
+conda env create -f environment.yml
+conda activate fanuc-rise
+```
+
+### 2) Frontend dependencies
+```bash
+cd advanced_cnc_copilot/frontend-react && npm install
+cd ../frontend-vue && npm install
+```
+
+### 3) Quick dependency diagnostics
+```bash
+python --version
+pip check
+npm --version
+npm ls --depth=0
+```
+
+### 4) Runtime connectivity checks
+```bash
+# API health
+curl -s http://localhost:8000/api/health
+
+# Dashboard websocket (machine-scoped)
+# ws://localhost:8000/ws/telemetry/CNC-001
+```
+
+If machine-scoped telemetry is unavailable in your current backend mode, the dashboard now falls back to the global stream endpoint (`/ws/telemetry`).
+
+## How to Train the LLM with the Simulator (Practical Loop)
+
+Use this loop to improve planning quality without risking hardware:
+
+1. **Generate scenario batches**
+   - Use simulator variants (normal, chatter, thermal drift, spindle stall) to create trajectories.
+   - Save each run as `{input_intent, telemetry_trace, action_trace, outcome, safety_flags}`.
+
+2. **Build supervised preference data**
+   - For each scenario, keep:
+     - `creator_proposal` (candidate plan)
+     - `auditor_verdict` (pass/fail + rule trace)
+     - `accountant_score` (time/cost impact)
+   - Convert this into preference pairs (`good_plan`, `bad_plan`) for fine-tuning or ranking.
+
+3. **Train in phases**
+   - **SFT phase**: train on accepted plans and corrective rewrites.
+   - **Reward/ranking phase**: train a scorer on safety + economics labels.
+   - **Policy improvement phase**: optimize for high reward under strict safety constraints.
+
+4. **Gate with deterministic safety**
+   - Keep Physics Auditor and hard constraints outside the model.
+   - Reject any proposal violating vibration/load/curvature bounds even if model confidence is high.
+
+5. **Deploy as shadow mode first**
+   - Run the model in recommendation-only mode.
+   - Compare proposed actions vs executed actions and measure regret/safety deltas before enabling active control.
+
+### Suggested training metrics
+- Safety violation rate
+- Auditor rejection rate
+- Cycle-time improvement
+- Surface finish proxy / quality score
+- Recovery latency after injected fault
+
+## Additional Critical Recommendations
+
+- **Do not remove deterministic guardrails** when increasing model autonomy.
+- **Version telemetry schemas** so training data stays compatible over time.
+- **Record full reasoning traces** for post-incident audits.
+- **Keep a simulator parity suite** that replays historical failure windows before each release.
+
 ## Usage Examples
 
 ### Starting the Application

advanced_cnc_copilot/SYSTEM_ARCHITECTURE.md

@@ -93,3 +93,60 @@ graph TD
     *   Real-time telemetry (Load/Vibration) feeds the **Dopamine Engine**.
     *   Post-job quality (Vision) feeds the **Reinforcement Learning** model.
     *   The system updates its "Risk Tolerance" weights for the next cycle.
+
+## Operational Debug Playbook (Dependencies + Runtime)
+
+### Dependency layers
+- **Python services**: FastAPI backend, orchestration core, simulator and HAL adapters.
+- **Frontend services**: dashboard clients (React/Vue/HTML) consuming REST + WebSocket.
+- **Data services**: Postgres/TimescaleDB and optional Redis.
+
+### Minimal boot order
+1. Install Python dependencies and activate environment.
+2. Install frontend dependencies in each UI package.
+3. Start backend API (`uvicorn backend.main:app --reload`).
+4. Open dashboard and verify `/api/health` + websocket stream.
+
+### Failure isolation checklist
+- If REST works but live widgets do not update: inspect WebSocket route mismatch first.
+- If machine-specific stream fails: verify `/ws/telemetry/{machine_id}` and then fallback to `/ws/telemetry`.
+- If optimization endpoints fail: validate model/agent initialization and dependency imports before checking UI.
+
+## LLM Training Architecture on Simulator
+
+```mermaid
+graph LR
+    A[Scenario Generator\n(normal/fault/thermal/chatter)] --> B[Telemetry + Action Dataset]
+    B --> C[SFT Dataset Builder\n(prompt->plan)]
+    B --> D[Preference Dataset Builder\n(good vs bad plan)]
+    C --> E[Policy Model (Creator)]
+    D --> F[Reward/Rank Model]
+    E --> G[Shadow Deployment]
+    F --> G
+    G --> H[Auditor + Physics Constraints]
+    H --> I[Accepted Actions + Outcomes]
+    I --> B
+```
+
+### Safety-first training contract
+- Creator model can **propose**, never unilaterally execute.
+- Auditor/physics layer remains deterministic and blocks out-of-bounds actions.
+- Training data must include both successful and failed episodes to avoid optimism bias.
+
+### Recommended dataset schema
+- `intent_text`
+- `machine_context` (tool, material, wear state)
+- `telemetry_window` (time-series)
+- `proposed_action`
+- `auditor_result` + `reasoning_trace`
+- `execution_outcome` (cycle time, quality, fault/no-fault)
+- `economic_score`
+
+### Deployment maturity gates
+1. Offline simulator benchmark pass.
+2. Shadow mode acceptance thresholds met.
+3. Controlled pilot on non-critical operations.
+4. Progressive rollout with rollback triggers.
+
+## Further Reading
+- Operational and contract details: `docs/TECHNICAL_REFERENCE.md`.