refactor(docs): move requirements and test infra docs into docs/ subdirectories

Organize documentation by moving requirements (HighLevelReqs, Component-*,
lmxproxy_protocol) to docs/requirements/ and test infrastructure docs to
docs/test_infra/. Updates all cross-references in README, CLAUDE.md,
infra/README, component docs, and 23 plan files.
This commit is contained in:
Joseph Doherty
2026-03-21 01:11:35 -04:00
parent 0a85a839a2
commit d91aa83665
52 changed files with 486 additions and 124 deletions

View File

@@ -13,8 +13,8 @@ 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 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.
3. **Requirements traceability at bullet level** — every individual requirement (each bullet point, sub-bullet, and constraint) in docs/requirements/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 docs/requirements/Component-*.md documents contain implementation constraints not present in docs/requirements/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, not blocking** — any ambiguity discovered during plan generation is logged in `docs/plans/questions.md` and generation continues. Do not stop or wait for user input during plan generation.
7. **Codex MCP is best-effort** — if the Codex MCP tool is unavailable or errors during verification, note the skip in the plan document and continue. Do not block on external tool availability.
@@ -445,8 +445,8 @@ For each phase, the implementation plan document must contain:
1. **Scope** — Components and features included
2. **Prerequisites** — Which phases/components must be complete
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.
3. **Requirements Checklist** — A bullet-level checklist extracted from docs/requirements/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 docs/requirements/Component-*.md documents, each mapped to a work package.
5. **Work Packages** — Numbered tasks with:
- Description
- Acceptance criteria (must cover every checklist bullet mapped to this work package)
@@ -489,8 +489,8 @@ These are mapped to work packages and verified in acceptance criteria just like
### Generation Steps
1. Read the phase definition in this document
2. Read all referenced Component-*.md documents
3. Read referenced HighLevelReqs.md sections **line by line** — extract every bullet, sub-bullet, and constraint as a numbered requirement
2. Read all referenced docs/requirements/Component-*.md documents
3. Read referenced docs/requirements/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
@@ -516,8 +516,8 @@ After the orphan check passes, submit the plan to the Codex MCP tool (model: `gp
**Step 1 — Requirements coverage review**: Submit the following as a single Codex prompt:
- The complete phase plan document
- The full text of every HighLevelReqs.md section this phase covers
- The full text of every Component-*.md document referenced by this phase
- The full text of every docs/requirements/HighLevelReqs.md section this phase covers
- The full text of every docs/requirements/Component-*.md document referenced by this phase
- The relevant Key Design Decisions from CLAUDE.md
Ask Codex: *"Review this implementation plan against the provided requirements, component designs, and design constraints. Identify: (1) any requirement bullet, sub-bullet, or constraint from the source documents that is not covered by a work package or acceptance criterion in the plan, (2) any acceptance criterion that does not actually verify its linked requirement, (3) any contradictions between the plan and the source documents. List each finding with the specific source text and what is missing or wrong."*