feat: cheat sheet → CRE mapping suggestion contract (Workstream F, F1–F2)

[skypank-coder]

What & why

First slice of Workstream F from the "Autonomous LLM Pipeline for Cheat Sheet → CRE
Mapping" RFC: the suggestions.json data contract (checkpoints F1–F2). This is the
review-first artifact schema the rest of the pipeline reads and writes; landing it
alone lets the contract be reviewed before the adapter and CLI build on it.

Scope (F1–F2 only)

• SUGGESTIONS_SCHEMA — JSON Schema (draft-07) for the §4 suggestion item;
  additionalProperties: false, required-field lists, status/confidence enums,
  score bounded [0,1].
• CandidateCRE + MappingSuggestion dataclasses (advisory fields carried through).
• write_suggestions_json — deterministic (sorted keys, self-validates before writing).
• load_approved_suggestions — validate → parse → filter status == "approved";
  violations raise SuggestionSchemaError naming the offending field path.

Not in this PR (follow-ups)

• F3 suggestions_to_parse_result (the import adapter — touches defs.Standard /
  ParseResult / Node_collection). The reconciliation design (title→section,
  build_tags/validate_classification_tags, fixed name="OWASP Cheat Sheets", skip
  zero-link Standards, drop advisory fields) is captured as docstring notes for that PR.
• F4/F5 CLI + end-to-end wiring.

Tests

8 tests, no Postgres/Neo4j needed: valid fixture validates, invalid fixture fails schema,
malformed load raises a field-named error, only-approved filtering, nested CandidateCRE
parsing, write→load round-trip, write determinism, written file re-validates.

Notes

• jsonschema is a dev dependency — F is offline import tooling, matching existing
  repo usage (application/tests/librarian/*). Promote to requirements.txt if F ever runs
  in prod.
• mypy: only note is jsonschema missing library stubs (import-untyped), consistent with
  existing modules; repo has no mypy gate.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: b94a0091-7e18-40df-8d41-ba1ed0f47777

📥 Commits

Reviewing files that changed from the base of the PR and between 20abd65 and d21cdb0.

📒 Files selected for processing (4)

• application/tests/cheatsheets_workstream_f_test.py
• application/tests/fixtures/cheatsheets_workstream_f/suggestions_invalid.json
• application/tests/fixtures/cheatsheets_workstream_f/suggestions_valid.json
• application/utils/external_project_parsers/parsers/cheatsheets_workstream_f.py

Included review availability: Your plan includes up to 2 reviews per rolling hour; 1 remains after this review.

---

Summary by CodeRabbit

• New Features

  • Added support for validating, writing, and loading cheatsheet-to-CRE suggestions in JSON format.
  • Added filtering to load only approved suggestions.
  • Added structured candidate CRE details, including scores, confidence levels, and reasons.
  • Added deterministic output and clear validation errors for malformed suggestion data.

• Tests

  • Added coverage for schema validation, nested candidate parsing, approved-suggestion filtering, round trips, and deterministic output.

Walkthrough

Adds the Workstream F suggestion schema, candidate and mapping dataclasses, deterministic JSON serialization, schema validation, approved-suggestion loading, malformed-input handling, and tests with valid and invalid fixtures.

Changes

Workstream F suggestion artifacts

Layer / File(s)	Summary
Suggestion contract and data model application/utils/external_project_parsers/parsers/cheatsheets_workstream_f.py	Defines suggestion statuses, confidence levels, JSON Schemas, SuggestionSchemaError, CandidateCRE, and MappingSuggestion.
Suggestion serialization and approved loading application/utils/external_project_parsers/parsers/cheatsheets_workstream_f.py	Adds deterministic schema-validated JSON writing, field-path validation errors, dataclass parsing, and filtering of approved suggestions.
Fixtures and adapter tests application/tests/cheatsheets_workstream_f_test.py, application/tests/fixtures/cheatsheets_workstream_f/*	Adds valid and malformed fixtures and tests schema validation, loading, round trips, deterministic output, and serialized-file validity.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to d21cd

This PR adds an offline, schema-validated suggestion contract with deterministic read/write behavior; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: northdpole, pa04rth, paoga87

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Workstream F1–F2 suggestions contract, which is the main change in the pull request.
Description check	✅ Passed	The description accurately explains the Workstream F1–F2 schema, dataclasses, JSON functions, tests, and deferred follow-up work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[northdpole]

Review — Workstream F F1–F2 (#1022)

Small, isolated checkpoint. F3 import conversion and CLI are correctly left out.

• JSON Schema + dataclasses match the documented contract (additionalProperties: false, required fields, status/confidence enums).
• write_suggestions_json validates before write; load_approved_suggestions schema-validates then filters to approved.
• Errors name the offending field (SuggestionSchemaError).
• Tests cover valid/invalid fixtures, approved-only load, nested candidates, and deterministic round-trip.
• jsonschema stays a dev dependency (requirements-dev.txt); module docstring flags promoting it if F ever runs in a prod import path.

CI green (Test / Lint / CodeQL). MERGEABLE. Approving and rebase-merging.