Version Update Validation Checklist

Quality gates to verify before finalizing a version update.

---

Pre-Release Checklist

SRS Validation

• ID Integrity

  • All new requirements have valid IDs (REQ-{DOMAIN}-{NNN})
  • No duplicate IDs within any domain
  • No ID reuse from deprecated requirements

• Content Completeness

  • All requirements have Statement
  • All requirements have at least one Acceptance Criterion
  • All requirements have Traceability (Source)
  • Error Handling documented for I/O and validation requirements

• Modification Tracking

  • Modified requirements preserve original ID
  • Reviewer Notes document significant changes
  • Deprecated requirements have deprecation notice

• Structure

  • Frontmatter complete (title, description, sidebar_position)
  • Traceability Matrix updated
  • Acceptance Tests updated for changed ACs

SDS Validation

• Content Updates

  • Architecture changes documented in sds-03-architecture-overview.md
  • Data model changes documented in sds-04-data-architecture.md
  • Security changes documented in sds-05-security-architecture.md
  • Domain docs updated for behavior changes

• Cross-References

  • New sections have {#anchor-name} identifiers
  • sds-master-index.md updated for new sections
  • sds-ref-glossary.md updated for new terms

• Diagrams

  • ERD updated if entities changed
  • Architecture diagrams updated if components changed
  • Data flow diagrams updated if flows changed

• Rule Docs

  • Truth tables updated for rule changes
  • Rule Summary Block current
  • Precedence tables accurate

STD Validation

• Test cases added for new requirements
• Test cases updated for modified requirements
• Deprecated tests archived appropriately
• Coverage targets met (100% REQ, 80%+ AC)
• Traceability matrix current

Unified Traceability Validation

• Run python3 docusaurus/scripts/generate-unified-traceability.py --validate — check for warnings
• Run python3 docusaurus/scripts/generate-unified-traceability.py --render-md — regenerate all views
• Verify generated MD views have expected REQ count for this version
• No orphan requirements (every REQ in SRS has a traceability entry)
• VERSION constant in generate-unified-traceability.py (line 64) matches v{NEW}

Versioned Snapshot Integrity

• Frozen snapshot is the baseline — Never modify files in versioned_docs/version-X.Y.Z/ after freezing. If corrections are needed, apply them only to the working docs/ copy and note the discrepancy.
• Broken links in frozen snapshots are expected — Frozen snapshots may reference docs that were created after the freeze point. The v3.0.0 snapshot has 2 pre-existing broken links to guides created during later sessions. Do not attempt to fix these in the frozen copy.
• Version freeze timing — Freeze docs (npm run docusaurus docs:version {NEW}) only after ALL documentation updates (SRS, SDS, STD, code_tags, traceability) are complete. Premature freezing creates a stale snapshot that diverges from the working copy.

Test Environment Validation

• .env.test-baseline exists and reflects working test config
• All pool DBs migrated to v{NEW} schema (migrate:fresh with --path flags)

Regression Testing Validation

• Full regression run completed with --target-version X.Y.Z (uses the NEW version to exclude old-version-only tests)

  python3 behat-optimizer.py run --target-version X.Y.Z --suite all --rerun-failures

• KNOWN_VERSION_TAGS and LATEST_VERSION_TAG updated in tests/scripts/behat-optimizer.py
• All new failures classified (regression, flaky, pre-existing, environment)
• No unresolved new regressions — all either fixed or tagged KCI/KL with justification
• Stale KCI/KL tags audited — remove tags for issues fixed in v{NEW}
• Browser regression run completed (correct Cognito, Pusher, artisan config verified)

Mermaid Diagram Validation

• All diagrams render without errors

  bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs  # Should report 0 errors

• Common syntax issues avoided

  • No pipe chars |...| in node labels (conflicts with edge syntax)
  • Node IDs don't match subgraph IDs (causes cycle errors)
  • Special chars (@, (), <br/>) in labels are quoted
  • Cross-subgraph connections defined outside subgraph blocks

Code Mapping Validation

Note: All checks use tests/catalogue/code_tags.json as the single source of truth for code-to-requirement mappings.

• Orphan Check

  # No references to non-existent requirements
  jq -r '.by_srs | keys[]' tests/catalogue/code_tags.json | sort -u > /tmp/code-refs.txt
  grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/ | sort -u > /tmp/srs-ids.txt
  comm -23 /tmp/code-refs.txt /tmp/srs-ids.txt
  # Should return empty

• View Consistency Check

  # All files in by_srs must also appear in by_file
  jq -r '.by_srs | to_entries[] | .value[]' tests/catalogue/code_tags.json | sort -u > /tmp/srs-files.txt
  jq -r '.by_file | keys[]' tests/catalogue/code_tags.json | sort -u > /tmp/byfile-files.txt
  comm -23 /tmp/srs-files.txt /tmp/byfile-files.txt
  # Should return empty

• Empty Entry Check

  # No entries with empty SRS and SDD arrays
  jq '.by_file | to_entries[] | select(.value.srs == [] and .value.sdd == []) | .key' tests/catalogue/code_tags.json
  # Should return empty

• Implementation Sections

  • New requirements with code have Implementation section
  • Modified code has updated Implementation section
  • No stale Implementation references

---

Finalization Checklist

Version Metadata

• Document Headers

  • Version number updated in SDS files
  • Last Updated date current
  • Change Summary added where appropriate

• CLAUDE.md

  • Current status section updated
  • Version number updated
  • Active work section reflects completion

Release Artifacts

• Release notes created: docusaurus/docs/release-notes-v{NEW}.md
• Docusaurus version freeze completed:

  cd docusaurus && npm run docusaurus docs:version {NEW}

• versions.json lists the new version correctly
• STR (Software Test Report) generated from regression results:

  python3 behat-optimizer.py report \
    --traceability /path/to/unified-traceability.json \
    --render-md /path/to/str-release-test-report.md

Transition Notes

• Handover notes
  • Created or updated for the next contributor
  • Current phase documented
  • Remaining work listed
  • Key decisions documented

Git Operations

• Commit Structure

  • Meaningful commit messages
  • One concern per commit where practical
  • No unrelated changes mixed

• Tagging

  • Consider creating version tag
  • Example: git tag v{X.Y}-docs-complete

---

Validation Scripts

Full Validation Suite

#!/bin/bash
# validate-version-update.sh

echo "=== Version Update Validation ==="
echo ""

# 1. Check for orphan SRS refs in code_tags.json
echo "1. Checking for orphan SRS references..."
jq -r '.by_srs | keys[]' tests/catalogue/code_tags.json 2>/dev/null | sort -u > /tmp/code-refs.txt
grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/ 2>/dev/null | sort -u > /tmp/srs-ids.txt
ORPHANS=$(comm -23 /tmp/code-refs.txt /tmp/srs-ids.txt | wc -l)
if [ "$ORPHANS" -gt 0 ]; then
  echo "   FAIL: $ORPHANS orphan references found"
  comm -23 /tmp/code-refs.txt /tmp/srs-ids.txt | head -10
else
  echo "   PASS: No orphan references"
fi
echo ""

# 2. Check for code_tags.json view consistency
echo "2. Checking code_tags.json view consistency..."
INCONSISTENT=$(comm -23 \
  <(jq -r '.by_srs | to_entries[] | .value[]' tests/catalogue/code_tags.json 2>/dev/null | sort -u) \
  <(jq -r '.by_file | keys[]' tests/catalogue/code_tags.json 2>/dev/null | sort -u) | wc -l)
if [ "$INCONSISTENT" -gt 0 ]; then
  echo "   FAIL: $INCONSISTENT files in by_srs missing from by_file"
else
  echo "   PASS: All views consistent"
fi
echo ""

# 3. Check SRS files have required sections
echo "3. Checking SRS file structure..."
for file in docusaurus/docs/srs/*.md; do
  if [ -f "$file" ] && [ "$(basename $file)" != "introduction.md" ] && [ "$(basename $file)" != "known-issues.md" ] && [ "$(basename $file)" != "nfr.md" ]; then
    # Check for Overview or Statement (new format)
    if ! grep -q "^## Overview\|^## Statement" "$file"; then
      echo "   WARN: $file missing Overview/Statement section"
    fi
  fi
done
echo "   Structure check complete"
echo ""

# 4. Validate Mermaid diagrams
echo "4. Validating Mermaid diagrams..."
if [ -f "docusaurus/scripts/validate-mermaid.sh" ]; then
  MERMAID_ERRORS=$(bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs 2>&1 | grep "^Errors:" | awk '{print $2}')
  if [ "$MERMAID_ERRORS" -gt 0 ] 2>/dev/null; then
    echo "   FAIL: $MERMAID_ERRORS Mermaid diagram errors"
  else
    echo "   PASS: All Mermaid diagrams valid"
  fi
else
  echo "   SKIP: validate-mermaid.sh not found"
fi
echo ""

# 5. Count stats
echo "5. Documentation Statistics:"
SRS_COUNT=$(ls docusaurus/docs/srs/*.md 2>/dev/null | wc -l)
RULES_COUNT=$(ls docusaurus/docs/srs/rules/*.md 2>/dev/null | wc -l)
SDS_COUNT=$(find docusaurus/docs/sds -name "*.md" 2>/dev/null | wc -l)
STD_COUNT=$(find docusaurus/docs/std -name "*.md" 2>/dev/null | wc -l)
REQ_COUNT=$(grep -roh "^## REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md 2>/dev/null | wc -l)
echo "   SRS files: $SRS_COUNT"
echo "   Rule files: $RULES_COUNT"
echo "   SDS files: $SDS_COUNT"
echo "   STD files: $STD_COUNT"
echo "   Total requirements: $REQ_COUNT"
echo ""

echo "=== Validation Complete ==="

Quick Validation

# Quick check - just count issues
jq -r '.by_srs | keys[]' tests/catalogue/code_tags.json | sort -u > /tmp/cr.txt
grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/ | sort -u > /tmp/sr.txt
echo "Orphan refs: $(comm -23 /tmp/cr.txt /tmp/sr.txt | wc -l)"

# Docusaurus link validation (authoritative)
cd docusaurus && npm run build 2>&1 | grep -c "couldn't be resolved"  # Should be 0

# Mermaid diagram validation
bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs  # Should report 0 errors

---

Common Issues and Fixes

Issue	Symptom	Fix
Orphan REQ ref	REQ-XXX-NNN in code_tags.json but not in SRS	Add requirement to SRS or remove mapping
Inconsistent views	File in by_srs but missing from by_file	Add missing by_file entry
Empty entry	code_tags.json entry with empty srs and sdd	Add references or remove entry
Missing Implementation	REQ has code but no Implementation section	Add Implementation section to SRS
Stale Implementation	Implementation section references moved/deleted code	Update to current locations
Missing Traceability	Requirement has no Source	Add Source to Traceability section
Broken Docusaurus link	Build warning "couldn't be resolved"	Check path (no /srs/ prefix), run fix-docusaurus-links.py
Mermaid parse error	validate-mermaid.sh reports errors	Quote special chars, rename conflicting node/subgraph IDs

---

Sign-Off

Before declaring version update complete:

Version Update Sign-Off

Version: v{X.Y}
Date: {YYYY-MM-DD}
Updated By: {Name/Session}

Code & Environment:
- [ ] Code upgraded to v{NEW} — all files match upstream
- [ ] .env.test-baseline created
- [ ] All pool DBs migrated to v{NEW} schema

Validation Results:
- [ ] Orphan refs: 0
- [ ] code_tags.json views consistent
- [ ] No empty code_tags.json entries
- [ ] Docusaurus build: 0 broken links
- [ ] Mermaid diagrams: 0 errors
- [ ] All SRS updated
- [ ] All SDS updated
- [ ] All STD updated

Testing:
- [ ] Full regression run with --target-version: all failures classified
- [ ] Stale KCI/KL tags audited for v{NEW} fixes
- [ ] Browser regression completed

Release Artifacts:
- [ ] generate-unified-traceability.py VERSION constant updated
- [ ] Release notes created (release-notes-v{NEW}.md)
- [ ] STR generated from regression results
- [ ] Docusaurus version freeze completed (docs:version)
- [ ] versions.json verified

Finalization:
- [ ] CLAUDE.md updated
- [ ] Transition notes created

Notes:
{Any exceptions or known issues}