Scout Requirements Archive

A project to archive Scouts BSA merit badge requirements and Cub Scout adventures.

Goals:

• Have machine-readable versions of merit badges and Cub Scout adventures with their requirements
• Ability to review the history of requirements as they evolve via git commits
• A simple static site of all merit badges and adventures deployed to GitHub pages

Usage

Merit Badges

Create the merit badge archive:

make archive-merit-badges

Validate the merit badge archive:

make validate-merit-badges

Validation warns about identical sibling leaf instructions, including exports that still contain inline resource titles. These warnings request source review; they do not change or remove official wording. The duplicate-content source evidence records the Athletics 5.option-g.2.e/.f and Insect Study 9.a/.b issues verified on the official pages on October 21, 2026. Both remain upstream-source issues pending an official correction. Complete requirement HTML fixtures and release text/hierarchy snapshots accompany the evidence for offline regression testing.

Validation also checks repeated action leaves across mandatory instruction groups within an explicit “Do ALL of the following” option. It does not compare separate alternatives. Golf source evidence records the official page's repeated history instruction at 2.option-b.2 and 2.option-b.3.a (reported downstream as .3.1). The linked 2026 pamphlet refers readers to the web requirements; it provides no replacement wording. Both entries, their IDs, links, response flags, and hierarchy remain preserved. The complete release141 semantic tree is an offline regression fixture.

The release141 Insect Study recheck confirms that both distinct source elements belong to requirement 9, Careers and Hobbies, and that the beekeeping resource belongs to 9.b. The linked 2026 pamphlet directs readers back to the live page for current requirements; it supplies no alternate hobby instruction. The provenance record includes response hashes and heading/parent associations. Regression coverage preserves all 33 requirement nodes and 39 structured requirement resources, including the separate resources on both repeated choices. An official clarification is still required before changing 9.b; the duplicate warning is the intended diagnostic, not an extraction failure.

Generate the merit badge index file:

make index-merit-badges

Generate merit badge change report:

make report-merit-badges

Cub Scout Adventures

Create the Cub Scout adventures archive:

make archive-cub-adventures

Clean only Cub Scout adventures output:

make clean-cub-adventures

Validate the Cub Scout adventures archive:

make validate-cub-adventures

Generate the Cub Scout adventures index file:

make index-cub-adventures

Generate Cub Scout adventures change report:

make report-cub-adventures

Combined Operations

Run the entire merit badge archiving process (archive, index, validate, and report):

make all

Run both merit badges and Cub Scout adventures archiving:

make all-with-cub-adventures

Run code quality checks:

make check

Output Format

The project generates two types of files for each merit badge and Cub Scout adventure:

1. JSON files: Structured data including name, overview, requirements, activities, etc.
2. Markdown files: Human-readable format of the requirements

Merit Badges

• Stored in build/merit-badges/
• Include Eagle-required status, PDF links, and shop URLs
• Images stored in build/merit-badges/images/

Cub Scout Adventures

• Organized by rank in build/cub-scout-adventures/{rank}/
• Include adventure type (Required/Elective), category, and detailed activities
• Activities include location, energy level, supply requirements, and prep time
• Images stored in build/cub-scout-adventures/{rank}/images/

Historical Change Tracking

Changes to requirements are tracked and preserved using Git's version control:

1. Individual Files: Each merit badge and adventure is stored as separate JSON and Markdown files
2. Git History: Changes are committed only when requirements actually differ
3. Detailed Commit Messages: Commit messages include which items were added, removed, or modified
4. Web Interface: A GitHub Pages site provides access to current requirements with links to Git history

Website

The project automatically deploys a simple website to GitHub Pages that includes:

• An index of all available merit badges and Cub Scout adventures
• Individual pages for each item with full requirements
• Links to original scouting.org pages and resources
• Images for each badge and adventure

Automated Archive

The project includes GitHub Actions workflows that:

1. Run archive process automatically on a schedule
2. Generate structured comparison reports between archive runs
3. Commit changes to the repository with detailed commit messages
4. Deploy an updated website to GitHub Pages

You can also manually trigger these workflows from the GitHub Actions tab.

Troubleshooting

Manual Intervention

In case of failures:

1. Use the workflow_dispatch trigger to manually run the archiver
2. Check the GitHub Actions logs for detailed error information
3. Run the validation steps to identify specific issues:

   make validate-merit-badges
   make validate-cub-adventures

4. Run the archivers locally to debug issues:

   make archive-merit-badges
   make archive-cub-adventures