Code Mapping Update Guide

How to maintain bidirectional traceability between code and documentation.

Note: This guide supersedes the previous inline DocRef comment approach. Code-to-requirement mappings are now maintained in code_tags.json as the single source of truth. No inline DocRef: comments in PHP/Vue source files are needed.

Reference Document

• Legacy DocRef Format & Rules: llm-instructions/archive/CODE_REVIEW_PLAN.md (archived)

---

Overview

Code mappings create bidirectional links:

• Code to Docs: Entries in code_tags.json map code files to SRS/SDS
• Docs to Code: Implementation sections in SRS point to code

This enables:

• Navigating from any requirement to implementing code
• Navigating from any code boundary to governing requirements
• Impact analysis for changes

---

Registry Format

Location: tests/catalogue/code_tags.json

The registry has three views of the same data:

{
  "by_file": {
    "app/Http/Controllers/RunImportController.php": {
      "srs": ["REQ-RUNIMPORT-012", "REQ-AUDIT-004"],
      "sdd": ["sds-domain-fileimport.md#run-import-process"]
    }
  },
  "by_srs": {
    "REQ-RUNIMPORT-012": [
      "app/Http/Controllers/RunImportController.php",
      "app/Services/RunImportService.php"
    ]
  },
  "by_sdd": {
    "sds-domain-fileimport.md#run-import-process": [
      "app/Http/Controllers/RunImportController.php"
    ]
  }
}

View	Purpose
by_file	Given a code file, find all requirements and design sections it implements
by_srs	Given a requirement, find all code files that implement it
by_sdd	Given an SDS section, find all code files related to it

Normative Rules

1. Consistency: All three views must stay in sync. Adding a file-to-REQ mapping in by_file requires also adding the file under that REQ in by_srs.

2. Non-Empty: Every entry must reference at least one SRS ID or SDS anchor. Do not add entries with empty arrays.

3. Many-to-Many:

   • One code file can reference multiple REQs
   • One REQ can be referenced by multiple code files

---

What to Map

Add Entries for These (Navigation Anchor Points)

Category	Examples	Why
Entry Points	HTTP controllers, API routes, CLI commands	User-facing boundaries
Queue Workers	Jobs, event listeners	Async processing entry points
Core Domain Services	RulesEngine, RunImportService	Business logic centers
Persistence Boundaries	Migrations with logic, repositories	Data layer decisions
Integration Boundaries	S3, SES, Pusher, Cognito handlers	External system touchpoints

Do NOT Add Entries for These

Category	Examples	Why
Utilities	String helpers, formatters	No direct requirement mapping
Simple CRUD	Basic model accessors	Too granular
Presentational	Blade templates, simple Vue components	UI layer, not behavior
Config files	.env, config/*.php	Not code boundaries

---

Adding Mappings for New Code

Step 1: Identify the Requirement(s)

Find which SRS requirement(s) the code implements:

# Search for relevant requirements
grep -r "shall.*{keyword}" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/

Step 2: Identify the SDS Section(s)

Find which SDS section documents the design:

# Search for relevant design sections
grep -r "{keyword}" docusaurus/docs/sds/

Step 3: Add Entry to code_tags.json

Edit tests/catalogue/code_tags.json and add the file path to all three views:

1. Add the file under by_file with its srs and sdd arrays
2. Add the file path under each REQ ID in by_srs
3. Add the file path under each SDS anchor in by_sdd

Step 4: Add Implementation Section to SRS

In the relevant SRS file, add or update the Implementation section:

### Implementation

| Component | Location |
|-----------|----------|
| Controller | `{Controller}@{method}` |
| Service | `{Service}@{method}` |
| Job | `{JobClass}` |
| Model | `{Model}` |

---

Updating Mappings for Modified Code

When Requirement Scope Changes

If REQ-DOMAIN-001 is split into REQ-DOMAIN-001 and REQ-DOMAIN-002:

1. Find all code files mapped to REQ-DOMAIN-001 in by_srs
2. Determine which should reference the new REQ
3. Update code_tags.json entries accordingly (all three views)
4. Update Implementation sections in both SRS files

When Code is Refactored

If code moves from one class to another:

1. Remove the old file path from code_tags.json (all three views)
2. Add the new file path to code_tags.json (all three views)
3. Update Implementation section in SRS

---

Removing Mappings

When Requirement is Deprecated

1. Keep the mapping in code_tags.json until the code is actually removed
2. Optionally add a note in the SRS Implementation section

When Code is Removed

1. Remove the file from all three views in code_tags.json
2. Update Implementation section in SRS:
   • Mark as "Removed in v{X.Y}" or
   • Remove row entirely if requirement also removed

---

Validation

Check for Orphan SRS References

REQ IDs in code_tags.json that don't exist in SRS:

# Extract all REQ refs from code_tags.json
jq -r '.by_srs | keys[]' tests/catalogue/code_tags.json | sort -u > /tmp/code-refs.txt

# Extract all REQ IDs from SRS
grep -roh "REQ-[A-Z]*-[0-9]*" docusaurus/docs/srs/*.md docusaurus/docs/srs/rules/ | sort -u > /tmp/srs-ids.txt

# Find orphans (in code_tags.json but not defined in SRS)
echo "Orphan references (mapped in code_tags.json but not defined in SRS):"
comm -23 /tmp/code-refs.txt /tmp/srs-ids.txt

Check for Consistency Between Views

Verify that by_file, by_srs, and by_sdd are in sync:

# Check that every file in by_srs also appears 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
echo "Files in by_srs but missing from by_file:"
comm -23 /tmp/srs-files.txt /tmp/byfile-files.txt

Check for Missing Implementation Sections

SRS files with requirements but no Implementation section:

#!/bin/bash
# find-missing-impl.sh

echo "SRS files without Implementation sections:"

for file in docusaurus/docs/srs/*.md; do
  # Check if has requirements but no implementation
  if grep -q "^## REQ-" "$file" && ! grep -q "^## Implementation" "$file"; then
    echo "$file"
  fi
done

---

Quality Checklist

Before committing code_tags.json changes:

• All three views (by_file, by_srs, by_sdd) are consistent
• No empty arrays in any entry
• All referenced REQ IDs exist in SRS
• All referenced SDS anchors exist
• Implementation sections updated in affected SRS files
• Validation checks pass

---

Regenerate Unified Traceability

After updating code_tags.json, regenerate the unified traceability artifacts:

python3 docusaurus/scripts/generate-unified-traceability.py --render-md

This regenerates the unified traceability JSON and its auto-generated MD views (traceability matrix, coverage report, release checklist).

---

Tips

1. Update code_tags.json during development - Easier than retrofitting later
2. One concern per entry - Don't mix unrelated requirements in a single file mapping
3. Map boundaries, not internals - Focus on entry points and interfaces
4. Keep Implementation sections current - Update when code moves
5. Run validation before release - Catch broken links early