Skip to content

Commit 3ebd35e

Browse files
RhodosBergerRhodosBerger
committed
Standardize technical docs and roadmap traceability
1 parent 9f97e3d commit 3ebd35e

File tree

4 files changed

+128
-0
lines changed

4 files changed

+128
-0
lines changed

‎advanced_cnc_copilot/FEATURE_IMPLEMENTATION_BLUEPRINT.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,17 @@ This document turns the project roadmaps into an executable delivery plan. It is
66
- `cms/theories/PROJECT_STATE_AND_ROADMAP.md`
77
- `NEXT_STEPS_OVERVIEW.md`
88

9+
## 0) Roadmap Source Crosswalk (MD -> Implementation)
10+
11+
| Source document | What it contributes | Implemented as track |
12+
|---|---|---|
13+
| `ROADMAP_TO_ARCHITECTURE.md` | Macro architecture phases and target platform shape | A, B, E |
14+
| `IMPLEMENTATION_STRATEGY_PHASE2.md` | Mid-phase delivery and integration sequencing | B, C, D |
15+
| `cms/theories/PROJECT_STATE_AND_ROADMAP.md` | Current-state inventory + quarterly objectives | A, C, E |
16+
| `NEXT_STEPS_OVERVIEW.md` | Tactical next actions and commercialization flow | C, D, E |
17+
18+
This crosswalk exists so every roadmap statement is traceable to an engineering workstream.
19+
920
## 1) Dependency Baseline (must pass first)
1021

1122
### Required runtime layers
@@ -148,3 +159,15 @@ A feature is done only if all conditions hold:
148159
3. Implement Fleet selector persistence in dashboard UI.
149160
4. Add Auditor reason-code schema and include in websocket payload.
150161
5. Create simulator dataset export command for SFT + preference data.
162+
163+
164+
## 6) Documentation Standards Used
165+
166+
This blueprint follows documentation conventions commonly used in mature industrial software projects:
167+
- **Traceability**: each workstream references roadmap sources.
168+
- **Acceptance criteria**: every feature track has measurable outcomes.
169+
- **Operational readiness**: runability and fallback behavior are first-class requirements.
170+
- **Safety by design**: deterministic controls are explicit and mandatory.
171+
- **Lifecycle clarity**: includes implementation sequence, DoD, and immediate actions.
172+
173+
For low-level operational and contract details, see `docs/TECHNICAL_REFERENCE.md`.

‎advanced_cnc_copilot/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,13 @@ A three-agent system ensuring safe AI integration:
140140
- Nightmare Training for offline learning through simulation
141141

142142

143+
## Documentation Set (Complete)
144+
145+
- `README.md`: project entrypoint, setup, and quickstart.
146+
- `SYSTEM_ARCHITECTURE.md`: architecture and data-flow map.
147+
- `FEATURE_IMPLEMENTATION_BLUEPRINT.md`: roadmap-driven delivery blueprint.
148+
- `docs/TECHNICAL_REFERENCE.md`: production-style technical contracts, NFRs, safety and release criteria.
149+
143150
## Delivery Blueprint (Roadmap -> Execution)
144151

145152
- **Feature execution plan**: `FEATURE_IMPLEMENTATION_BLUEPRINT.md` (maps roadmap docs into tracks, sprints, DoD, and acceptance criteria).

‎advanced_cnc_copilot/SYSTEM_ARCHITECTURE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,3 +147,6 @@ graph LR
147147
2. Shadow mode acceptance thresholds met.
148148
3. Controlled pilot on non-critical operations.
149149
4. Progressive rollout with rollback triggers.
150+
151+
## Further Reading
152+
- Operational and contract details: `docs/TECHNICAL_REFERENCE.md`.

‎advanced_cnc_copilot/docs/TECHNICAL_REFERENCE.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Technical Reference (Production-Style Documentation)
2+
3+
> This document follows common standards used in industrial software projects: system context, component contracts, operational runbook, non-functional requirements, and release gates.
4+
5+
## 1. System Context
6+
7+
FANUC RISE consists of five technical planes:
8+
1. **Control plane**: APIs, auth, orchestration, RBAC.
9+
2. **Data plane**: telemetry ingestion, storage, query and aggregation.
10+
3. **Decision plane**: Shadow Council agents (Creator, Auditor, Accountant).
11+
4. **Execution plane**: HAL/FOCAS bridge, simulator fallback.
12+
5. **Experience plane**: dashboard/hub/fleet UX.
13+
14+
## 2. Core Interfaces (contracts)
15+
16+
### REST interfaces
17+
- `GET /api/health`: liveness/readiness summary.
18+
- `POST /api/manufacturing/request`: unified orchestration entrypoint.
19+
- `POST /conduct`: creative scenario endpoint.
20+
- `POST /optimize`: optimization endpoint with material context.
21+
22+
### WebSocket interfaces
23+
- Primary machine-scoped stream: `/ws/telemetry/{machine_id}`.
24+
- Global fallback stream: `/ws/telemetry`.
25+
26+
### Contract requirements
27+
- Payloads must include `timestamp`, machine identity, and typed telemetry fields.
28+
- Safety-related actions must include a machine-readable `reason_code`.
29+
- Backward compatibility policy: additive changes only for minor versions.
30+
31+
## 3. Non-Functional Requirements (NFR)
32+
33+
### Reliability
34+
- Circuit breaker in HAL path.
35+
- Simulator fallback when hardware path is degraded.
36+
- Explicit retry strategy for websocket reconnection.
37+
38+
### Performance
39+
- Telemetry pipeline objective: p95 ingest->UI under 100ms in simulation.
40+
- API p95 latency budget defined per endpoint class (read/write/control).
41+
42+
### Security
43+
- RBAC-scoped access for operator/engineer/admin roles.
44+
- Token-based authentication for control endpoints.
45+
- Audit logs for all policy-overridden or blocked actions.
46+
47+
### Observability
48+
- Health, error rate, and throughput per subsystem.
49+
- Decision traces for AI + deterministic auditor outcomes.
50+
- Alerting for telemetry stalls and repeated fallback events.
51+
52+
## 4. Safety Model (critical technical details)
53+
54+
Safety is deterministic-first:
55+
1. Creator can propose only.
56+
2. Auditor validates against hard physics/policy limits.
57+
3. Accountant score is advisory and never bypasses constraints.
58+
4. Execution only after deterministic pass.
59+
60+
**Important:** model confidence is not considered a safety signal; only policy conformance and measured machine state are valid safety gates.
61+
62+
## 5. Data and Training Pipeline
63+
64+
### Dataset minimum schema
65+
- `intent_text`
66+
- `machine_id`
67+
- `telemetry_window`
68+
- `candidate_actions`
69+
- `auditor_verdict`
70+
- `reason_codes`
71+
- `execution_outcome`
72+
- `economic_score`
73+
74+
### Training pipeline stages
75+
1. Scenario generation (normal/fault/adversarial).
76+
2. Supervised fine-tuning dataset assembly.
77+
3. Preference/ranking dataset assembly.
78+
4. Offline benchmark and safety scoring.
79+
5. Shadow deployment with rejection telemetry.
80+
81+
## 6. Release Readiness Checklist
82+
83+
A release candidate is acceptable only if:
84+
- Dependency bootstrap script passes in clean environment.
85+
- API health/readiness checks pass.
86+
- Websocket primary/fallback behavior is validated.
87+
- Safety policy regression suite passes.
88+
- Documentation updates are complete and versioned.
89+
90+
## 7. Recommended Documentation Set (for this repo)
91+
92+
- `README.md`: entry-level setup and links.
93+
- `SYSTEM_ARCHITECTURE.md`: conceptual and flow architecture.
94+
- `FEATURE_IMPLEMENTATION_BLUEPRINT.md`: delivery execution plan.
95+
- `docs/TECHNICAL_REFERENCE.md` (this file): contracts, NFRs, runbook-grade guidance.

0 commit comments

Comments
 (0)