feat: add xlsx-to-oscal-poam task for poam transformation

[allanilya]

• Implements xlsx-to-oscal-poam task to transform FedRAMP POA&M Excel templates to OSCAL POAM JSON
• Supports all 31 FedRAMP POAM columns with comprehensive field mapping
• Creates linked PoamItem, Observation, and Risk objects per row
• Includes 34 unit tests with 100% coverage
• Adds complete tutorial documentation
• Uses deterministic UUIDs for stable updates
• Supports validation modes (on/warn/off)

Types of changes

• Hot fix (emergency fix and release)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Documentation (change which affects the documentation site)
• Breaking change (fix or feature that would cause existing functionality to change)
• Release (develop -> main)

Quality assurance (all should be covered).

• My code follows the code style of this project.
• Documentation for my change is up to date?
• My PR meets testing requirements.
• All new and existing tests passed.
• All commits are signed-off.

Summary

This PR implements a new xlsx-to-oscal-poam task that transforms FedRAMP Plan of Action and Milestones (POA&M) Excel spreadsheets into OSCAL POAM JSON format.

Implemented (Phase 1):

• Transforms FedRAMP POAM Excel templates to OSCAL POAM JSON
• Supports all 31 FedRAMP POAM template columns
• Creates linked PoamItem, Observation, and Risk objects per row
• Includes 34 comprehensive unit tests (100% coverage)
• Complete tutorial documentation
• Deterministic UUID generation for stable updates
• Configurable validation modes (on/warn/off)
• Creates new POAM files from scratch

Future Enhancement (Phase 2):

• Update/merge support for existing POAM files (similar to csv-to-oscal-cd)
• This will allow reading existing POAM JSON, calculating changes, and preserving UUIDs

Key links:

• Sonar coverage

Before you merge

• Ensure it is a 'squash commit' if not a release.
• Ensure CI is currently passing
• Check sonar. If you are working for a fork a maintainer will reach out, if required.

[degenaro]

@allanilya Upon first look, this code is very good! Sorry I didn't enable the pipelines sooner. Some initial comments:

• run make code-format
• run make code-lint
• the output file name should be plan-of-action-and-milestones.json (not poam.json); I ran trestle validate against the renamed file and it worked!
• just a few signatures are missing typing: lines 78, 188, 338 should have -> None
• Please remove mentions of "FedRAMP" and (for consistency with other tasks) "Excel", such as:
  • Transform FedRAMP POAM Excel spreadsheets to OSCAL POAM JSON format.
  • Transform POAM spreadsheet to OSCAL POAM JSON format.

If you try trestle task xlsx-to-oscal-cd -i you'll see that the expected columns are listed. POAM should have likewise, I think.

For discussion: I'm not sure that validation of fields is needed? The trestle classes employ pydantic, which should enforced some level of validity. I worry that we'll wind up with the transformer and the pydantic classes having different opinions.

I'll take a longer look at the code soon. I have not looked at the doc yet...
I suppose that we are stuck with xlsx because the sample data is xlsx. I had in my mind that this would be csv-to-oscal-poam.
@vikas-agarwal76 comments?

[degenaro]

• Why are so many files changed? (index.nd et. al.)
• Why is there both xlsx and csv tasks?
• make test-cov fails
• make code-lint fails

[degenaro]

Here is the info from a similar trestle xlsx transformation task:

((venv.allanilya) ) degenaro:trestle.ws$ trestle task xlsx-to-oscal-cd -i
trestle.core.commands.task:101 WARNING: Config file was not configured with the appropriate section for the task: "[task.xlsx-to-oscal-cd]"
Help information for xlsx-to-oscal-cd task.

Purpose: From spread sheet and catalog produce OSCAL component_definition file.

Configuration flags sit under [task.xlsx-to-oscal-cd]:
  catalog-file      = (required) the path of the OSCAL catalog file.
  spread-sheet-file = (required) the path of the spread sheet file.
  work-sheet-name   = (required) the name of the work sheet in the spread sheet file.
                      column "ControlId" contains control ID.
                      column "ControlText" contains control text.
                      columns "NIST Mappings" contain NIST control mappings.
                      column "ResourceTitle" contains component name.
                      column "goal_name_id" contains goal name.
                      column "goal_version" contains goal version.
                      column "rule_name_id" contains rule name.
                      column "rule_version" contains rule version.
                      column "Parameter [optional parameter]" contains parameter name + description, separated by newline.
                      column "Values default , [alternatives]" contains parameter values.
  output-dir        = (required) the path of the output directory for synthesized OSCAL .json files.
  output-overwrite  = (optional) true [default] or false; replace existing output when true.
  filter-column     = (optional) column heading of yes/no values; process only "yes" rows.
  profile-type      = (optional) one of ['by-goal', 'by-rule', 'by-control', 'by-check']

The info output from the POAM task should be very similar, please.

[degenaro]

make mdformat is failing in the lint pipeline. Please try running make mdfomat locally on you laptop, then deliver the handful of updated files as part of this PR.