dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document LmxProxy protocol in DCL, strengthen plan generation traceability guards, and add UI constraints

Browse Source 
- Replace "custom protocol" placeholder with full LmxProxy details (gRPC transport, SDK API mapping, session management, keep-alive, TLS, batch ops)
- Add bullet-level requirement traceability, design constraint traceability (52 KDD + 6 CD), split-section tracking, and post-generation orphan check to plan framework
- Resolve Q9 (LmxProxy), Q11 (REST test server), Q13 (solo dev), Q14 (self-test), Q15 (Machine Data DB out of scope)
- Set Central UI constraints: Blazor Server + Bootstrap only, no heavy frameworks, custom components, clean corporate design
This commit is contained in:
Joseph Doherty
2026-03-16 15:08:57 -04:00
parent e3a418d603
commit a9fa74d5ac
7 changed files with 290 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/plans/generate_plans.md
View File

@@ -13,11 +13,13 @@ This document defines the phased implementation strategy for the ScadaLink SCADA
1. **Each phase produces a testable, working increment** — no phase ends with unverifiable work.
2. **Dependencies are respected** — no component is built before its dependencies.
3. **Requirements traceability** — every HighLevelReqs section and REQ-* identifier must map to at least one phase. See `docs/plans/requirements-traceability.md` for the full matrix.
4. **Questions are tracked** — any ambiguity discovered during plan generation is logged in `docs/plans/questions.md`.
5. **Plans are broken into implementable work packages** — each phase is subdivided into epics, each epic into concrete tasks with acceptance criteria.
6. **Failover and resilience are validated early** — not deferred to a final hardening phase. Each runtime phase includes failover acceptance criteria.
7. **Persistence/recovery semantics are defined before actor design** — Akka.NET actor protocols depend on recovery behavior.
3. **Requirements traceability at bullet level** — every individual requirement (each bullet point, sub-bullet, and constraint) in HighLevelReqs.md must map to at least one work package. Section-level mapping is insufficient — a section like "4.4 Script Capabilities" contains ~8 distinct requirements that may land in different phases. See `docs/plans/requirements-traceability.md` for the matrix.
4. **Design decision traceability** — the Key Design Decisions in CLAUDE.md and detailed design in Component-*.md documents contain implementation constraints not present in HighLevelReqs.md (e.g., Become/Stash pattern, staggered startup, Tell vs Ask conventions, forbidden script APIs). Each must trace to a work package.
5. **Split-section completeness** — when a HighLevelReqs section spans multiple phases, each phase's plan must explicitly list which bullets from that section it covers. The union across all phases must be the complete section with no gaps.
6. **Questions are tracked** — any ambiguity discovered during plan generation is logged in `docs/plans/questions.md`.
7. **Plans are broken into implementable work packages** — each phase is subdivided into epics, each epic into concrete tasks with acceptance criteria.
8. **Failover and resilience are validated early** — not deferred to a final hardening phase. Each runtime phase includes failover acceptance criteria.
9. **Persistence/recovery semantics are defined before actor design** — Akka.NET actor protocols depend on recovery behavior.
---
@@ -442,26 +444,70 @@ For each phase, the implementation plan document must contain:
1. **Scope** — Components and features included
2. **Prerequisites** — Which phases/components must be complete
3. **Work Packages** — Numbered tasks with:
3. **Requirements Checklist** — A bullet-level checklist extracted from HighLevelReqs.md for every section this phase covers (see Bullet-Level Extraction below). Each bullet is a checkbox that must map to a work package.
4. **Design Constraints Checklist** — Applicable constraints from CLAUDE.md Key Design Decisions and Component-*.md documents, each mapped to a work package.
5. **Work Packages** — Numbered tasks with:
- Description
- Acceptance criteria
- Acceptance criteria (must cover every checklist bullet mapped to this work package)
- Estimated complexity (S/M/L)
- Requirements traced (HighLevelReqs section + REQ-* IDs)
4. **Test Strategy** — Unit, integration, and failover tests required
5. **Verification Gate** — What must pass before the phase is considered complete
6. **Open Questions** — Any ambiguities discovered, added to `questions.md`
- Requirements traced (HighLevelReqs bullet IDs + REQ-* IDs + design constraint refs)
6. **Test Strategy** — Unit, integration, and failover tests required
7. **Verification Gate** — What must pass before the phase is considered complete
8. **Open Questions** — Any ambiguities discovered, added to `questions.md`
### Bullet-Level Extraction
When a phase covers HighLevelReqs sections, the plan must decompose each section into its individual requirements:
- Each bullet point or sub-bullet is a separate requirement line item.
- Each sentence within a bullet that introduces a distinct constraint or behavior is a separate requirement.
- Negative requirements ("cannot", "does not", "no") are explicit line items — they become acceptance criteria that verify the behavior is correctly prohibited.
- For sections split across phases, each phase lists only its bullets. After all plans covering that section are generated, verify the union is complete.
**Example**: Section 4.4 "Script Capabilities" decomposes into:
- `[4.4-1]` Read attribute values (live + static)
- `[4.4-2]` Write attributes — data-sourced writes go to DCL, value updates on device confirm
- `[4.4-3]` Write attributes — static writes persist to SQLite, survive restart/failover, reset on redeploy
- `[4.4-4]` CallScript with ask pattern, concurrent execution
- `[4.4-5]` CallShared executes inline (no separate actor)
- `[4.4-6]` ExternalSystem.Call() synchronous
- `[4.4-7]` ExternalSystem.CachedCall() with S&F
- `[4.4-8]` Send notifications
- `[4.4-9]` Database.Connection() for raw ADO.NET access
- `[4.4-10]` Cannot access other instances' attributes or scripts
### Design Constraint Extraction
Each phase plan must also scan the following sources for implementation constraints relevant to its components:
1. **CLAUDE.md → Key Design Decisions**: Each bullet is a constraint. Tag with `[KDD-category-N]` (e.g., `[KDD-runtime-3]` for "Staggered Instance Actor startup on failover").
2. **Component-*.md documents**: Design details beyond what HighLevelReqs specifies (e.g., connection actor Become/Stash pattern, health report monotonic sequence numbers, 30s keep-alive interval). Tag with `[CD-ComponentName-N]`.
These are mapped to work packages and verified in acceptance criteria just like HighLevelReqs bullets.
### Generation Steps
1. Read the phase definition in this document
2. Read all referenced Component-*.md documents
3. Read referenced HighLevelReqs.md sections
4. Cross-reference `requirements-traceability.md` to ensure coverage
5. Break sub-tasks into concrete work packages with acceptance criteria
6. Identify test scenarios
7. Write the plan document to `docs/plans/phase-N-<name>.md`
8. Update `requirements-traceability.md` with plan references
9. Log any questions to `questions.md`
3. Read referenced HighLevelReqs.md sections **line by line** — extract every bullet, sub-bullet, and constraint as a numbered requirement
4. Read CLAUDE.md Key Design Decisions — extract constraints relevant to this phase's components
5. Build the Requirements Checklist and Design Constraints Checklist
6. Break sub-tasks into concrete work packages with acceptance criteria, mapping every checklist item
7. Verify: every checklist item maps to at least one work package. Flag any orphans.
8. Identify test scenarios — negative requirements ("cannot", "does not") must have explicit test cases
9. Write the plan document to `docs/plans/phase-N-<name>.md`
10. Update `requirements-traceability.md` with bullet-level references
11. Log any questions to `questions.md`
### Post-Generation Verification (Orphan Check)
After writing a phase plan, perform this verification before considering it complete:
1. **Forward check**: Walk every item in the Requirements Checklist and Design Constraints Checklist. Confirm each maps to a work package with acceptance criteria that would fail if the requirement were not implemented.
2. **Reverse check**: Walk every work package. Confirm each traces back to at least one requirement or design constraint (no untraceable work).
3. **Split-section check**: For any HighLevelReqs section shared with another phase, list the bullets this phase does NOT cover and note which phase owns them. If a bullet is unowned, it's a gap — assign it.
4. **Negative requirement check**: Every "cannot", "does not", "no", "not" constraint has an acceptance criterion that verifies the prohibition (e.g., "Scripts cannot access other instances" → test that cross-instance access fails).
5. Record the verification result at the bottom of the plan document.
---