docs(requirements): move requirement type comment to separate line

[santi698]

This is required because Ketryx doesn't support inline comments in metadata fields.

[github-actions]

Claude finished @santi698's task —— View job

---

PR Review: Move requirement type comments to separate line

Reviewing changes for Ketryx compliance

Todo List

• Read sample requirement files to understand transformation pattern
• Verify consistency across all 50 changed files
• Check for requirement processing scripts that might be affected
• Verify commit message follows conventional commits
• Check CLAUDE.md for relevant documentation
• Provide comprehensive review feedback

---

✅ Review Summary

This is a documentation-only change that restructures requirement metadata to accommodate Ketryx's YAML front-matter parser. The change is well-executed, consistent, and safe to merge.

What Changed

Before:

itemType: Requirement
Requirement type: FUNCTIONAL # Software requirement (user)

After:

itemType: Requirement
# Software requirement (user)
Requirement type: FUNCTIONAL

Verification Results

✅ Consistency Check (PASS)

• 50 files changed (all in requirements/ directory)
• 100 insertions, 50 deletions (exactly 2 additions, 1 deletion per file)
• Three requirement types transformed consistently:
  • FUNCTIONAL: 39 files (Software requirements)
  • ENVIRONMENT: 9 files (Stakeholder requirements)
  • REGULATORY: 2 files (System requirements)
• Pattern verification: All 50 diff hunks follow identical transformation

✅ Commit Message (PASS)

docs(requirements): move requirement type comment to separate line

This is required because Ketryx doesn't support inline comments in metadata fields.

• Follows conventional commits format
• Correct type: docs (documentation change)
• Clear scope: requirements
• Descriptive rationale in body

✅ No Breaking Changes (PASS)

• No Python code changes: No scripts parse these requirement files
• No test changes needed: Requirements are metadata-only
• No tooling impact: Ketryx GitHub Action reads YAML front-matter only
• Human-readable: Comments preserved, just moved above the field

✅ CLAUDE.md Compliance (PASS)

• Change is documentation-only, no architecture impact
• No module boundaries affected
• No test markers needed (no code changes)
• Ketryx integration already documented in .github/CLAUDE.md

Context: Ketryx Integration

This SDK is a medical device software component with FDA/MDR regulatory requirements. Ketryx is the compliance traceability platform that:

1. Parses requirement files (requirements/*.md) for traceability matrix
2. Validates YAML front-matter fields like itemType, Requirement type, itemHasParent
3. Reports to regulatory bodies via .github/workflows/_ketryx_report_and_check.yml

Why this change is necessary:

Ketryx's YAML parser treats inline comments (# comment) as part of the field value, causing parsing failures. Moving comments to separate lines ensures clean metadata extraction while preserving human-readable documentation.

Historical Context

Recent requirement-related commits show active Ketryx integration work:

6fa2a03 docs(requirements): move requirement type comment to separate line
9e3fa3a Merge pull request #243 from aignostics/docs/PYSDK-18-fix-traceability
386c2bf docs(requirements): add missing itemTitle to system health and settings requirements
243323b docs: annotate requirement type in requirement files with the actual mapped value

This PR is part of a series to establish proper regulatory traceability infrastructure.

---

🎯 Recommendations

1. Consider Adding a Requirements README

Since these files have specific formatting constraints for Ketryx, consider creating requirements/README.md documenting:

# Requirements Format Specification

## YAML Front-Matter Fields

- `itemId`: Unique requirement identifier (e.g., SHR-APPLICATION-1)
- `itemTitle`: Human-readable title
- `itemType`: Must be "Requirement"
- `Requirement type`: One of FUNCTIONAL, ENVIRONMENT, REGULATORY
- `itemHasParent`: Parent requirement ID (for SWR linking to SHR)
- `Layer`: System layer (CLI, GUI, System)
- `Module`: SDK module name

## Ketryx Compatibility

⚠️ **DO NOT use inline comments in YAML fields** (e.g., `field: value # comment`)

Ketryx cannot parse inline comments. Use separate comment lines:

✅ Correct:
```yaml
# Software requirement (user)
Requirement type: FUNCTIONAL

❌ Incorrect:

Requirement type: FUNCTIONAL # Software requirement (user)

This would prevent future contributors from accidentally reintroducing inline comments.

### 2. Pre-commit Hook (Optional)

Consider adding a pre-commit check to validate requirement file format:

```bash
# Detect inline comments in YAML front-matter
grep -r "^[A-Za-z].*:.*#" requirements/*.md

This would catch violations before they reach CI.

3. No Further Changes Needed

• ✅ Commit message is excellent (clear rationale in body)
• ✅ No CHANGELOG entry needed (internal documentation)
• ✅ No test changes needed (no code impact)
• ✅ PR description is clear

---

📊 Change Impact

Category	Impact	Details
Code	None	No Python/TypeScript changes
Tests	None	No test files affected
CI/CD	Positive	Ketryx workflow will parse cleanly
Documentation	Positive	Comments preserved, better formatted
Users	None	Internal metadata files
Regulatory	Positive	Improved traceability compliance

---

🚀 Approval Recommendation

APPROVED ✅

This PR:

• ✅ Solves a real Ketryx parsing issue
• ✅ Is 100% consistent across all 50 files
• ✅ Has no breaking changes
• ✅ Follows conventional commits
• ✅ Is safe to merge immediately

No further action required from contributor.

---

Note: I cannot formally approve PRs due to GitHub App permissions, but this review serves as a strong recommendation for approval by a maintainer.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud