Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 28 additions & 19 deletions .github/workflows/resources.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,54 +4,63 @@ on:
push:
paths:
- "resources/**"
- "tests/**"
- "scripts/check-resources.py"
- "scripts/render-resource-guides.py"
- "scripts/new-course-workspace"
- "templates/course-workspace/resources.md"
- ".github/workflows/resources.yml"
pull_request:
paths:
- "resources/**"
- "tests/**"
- "scripts/check-resources.py"
- "scripts/render-resource-guides.py"
- "scripts/new-course-workspace"
- "templates/course-workspace/resources.md"
- ".github/workflows/resources.yml"

jobs:
resource-check:
runs-on: ubuntu-latest
steps:
- name: Checkout workspace
- name: Checkout Workspace
uses: actions/checkout@v4
- name: Checkout canonical OEE curriculum
- name: Checkout OEE for unmapped course scaffolding
uses: actions/checkout@v4
with:
repository: 0xbuffdev/open-engineering-education
path: _oee
persist-credentials: false
- name: Validate catalogue and OEE course mappings
run: python3 scripts/check-resources.py --oee _oee
- name: Verify rendered resource guides
- name: Validate catalogue only (no active v1 maps)
run: python3 scripts/check-resources.py
- name: Reject stale generated reading guides
run: python3 scripts/render-resource-guides.py --check
- name: Test course generator and learner file protection
- name: Strict v2 shape and pinned export regression suite
run: python3 -m unittest discover -s tests -p 'test_*.py' -v
- name: Verify unmapped scaffolding and preserve learner files
shell: bash
run: |
set -euo pipefail
bash -n scripts/new-course-workspace
dir="$(mktemp -d)"
trap 'rm -rf "$dir"' EXIT
mkdir -p "$dir/learner" "$dir/other"
OEE_REPO="$PWD/_oee" bash scripts/new-course-workspace SEF SEF1 "$dir/learner"
plan="$dir/learner/notes/SEF/SEF1/reading-plan.md"
log="$dir/learner/notes/SEF/SEF1/resources.md"
test -s "$plan"
grep -q "Module 10 — Hardware, Software & Booting" "$plan"
temp="$(mktemp -d)"
trap 'rm -rf "$temp"' EXIT
mkdir -p "$temp/learner" "$temp/other"
OEE_REPO="$PWD/_oee" bash scripts/new-course-workspace SEF SEF1 "$temp/learner"
plan="$temp/learner/notes/SEF/SEF1/reading-plan.md"
log="$temp/learner/notes/SEF/SEF1/resources.md"
test ! -e "$plan"
printf '\nLearner-owned entry\n' >> "$log"
if OEE_REPO="$PWD/_oee" bash scripts/new-course-workspace SEF SEF1 "$dir/learner"; then
if OEE_REPO="$PWD/_oee" bash scripts/new-course-workspace SEF SEF1 "$temp/learner"; then
echo "ERROR: existing learner directories were overwritten" >&2
exit 1
fi
grep -q "Learner-owned entry" "$log"
OEE_REPO="$PWD/_oee" bash scripts/new-course-workspace SEF SEF2 "$dir/other"
test ! -e "$dir/other/notes/SEF/SEF2/reading-plan.md"
OEE_REPO="$PWD/_oee" bash scripts/new-course-workspace SEF SEF2 "$temp/other"
test ! -e "$temp/other/notes/SEF/SEF2/reading-plan.md"
# Legacy source formats are not supported, even without a resource map.
mkdir -p "$temp/legacy-oee/curriculum/SEF" "$temp/legacy-learner"
printf '**Specification:** `v0.1.0`\n' > "$temp/legacy-oee/curriculum/SEF/SEF1.md"
if OEE_REPO="$temp/legacy-oee" bash scripts/new-course-workspace SEF SEF1 "$temp/legacy-learner"; then
echo "ERROR: legacy OEE format was accepted" >&2
exit 1
fi
test ! -e "$temp/legacy-learner/notes/SEF/SEF1"
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,9 +145,9 @@ A completion claim should be supported by inspectable evidence, not by a checked

## Public study resources

The [public resource library](resources/README.md) contains book and online references mapped to canonical OEE modules, as well as generated Markdown study guides. These resources support, but do not replace, the OEE curriculum. Chapter and section entries have verification labels; a module marked partial still has unresolved research gaps.
The [public resource library](resources/README.md) contains optional book and online resources and a strict v2 mapping schema. Its historical SEF1 mapping and guide have been retired because they describe a different curriculum. No reviewed v2 course mapping or guide is currently published.

For a mapped course, the generator validates the mapping against the local OEE checkout and produces a portable `reading-plan.md`. Python 3 is needed for this step. Public resource guides are separate from the private 0xNAND instructional content. Course generation never overwrites existing learner directories.
Courses currently initialize **without a reading-plan snapshot** while the new v2 map undergoes pinned-source and human editorial review. Learner-owned `resources.md` remains available, and existing learner directories are never overwritten. Public resources stay independent of private 0xNAND content.

## Evidence and reproducibility

Expand Down
62 changes: 25 additions & 37 deletions resources/README.md
Original file line number Diff line number Diff line change
@@ -1,50 +1,38 @@
# Public OEE resource library (SEF1 pilot)
# Public OEE resource library

This is the **public resource index** for [Open Engineering Education](https://github.com/0xbuffdev/open-engineering-education) independent study.
This library supports independent study of [Open Engineering Education](https://github.com/0xbuffdev/open-engineering-education). OEE owns course requirements, outcomes and assessments. This free Workspace owns optional resource recommendations and learner-authored records.

## Ownership
## Current mapping status

- **OEE** owns curriculum, outcomes, lesson order, assessments and completion requirements.
- **OEE Workspace** owns public resource metadata and optional course/module/lesson mappings.
- **Private 0xNAND Content** may import these mappings but adds its own instructional implementation. No private authored lessons are published here.
**No active reviewed course map or generated study guide is published.** The former SEF1 schema-v1 mapping describes a different curriculum. It is now a deliberately rejected [negative test fixture](../tests/fixtures/resource-map-v1-SEF1.json) and remains in Git history; its chapter assignments must not be transferred by module number.

## Browse
The public catalogue remains available: [books](catalog/books/) and [online resources](catalog/online/). The single [active mapping schema](schemas/course-map.schema.json) is **v2 only**, with an explicit OEE specification v0.2.0, exact 40-character lowercase source commit, canonical path, and optional outcome/assessment references. Module numbers, lesson locators and reading recommendations are scoped to the recorded revision.

- [SEF1 draft resource mapping](mappings/SEF/SEF1.json)
- [Book catalog](catalog/books/) and [online resources](catalog/online/)
- [Resource schema](schemas/resource.schema.json) and [mapping schema](schemas/course-map.schema.json)
The replacement SEF1 mapping requires independent editorial review under WS-I02. Until then, learner workspaces can be created **without a reading plan**; this is not an OEE completion gap.

Resource identifiers **B1, B7, B46, R89 and R90** are preserved from the private legacy catalogue. Define each resource once and reference its ID from any number of course maps. A course mapping follows the *current OEE module order*, not a textbook's chapter order.
## Editorial principles

This pilot uses JSON rather than YAML so that Python 3's standard library can validate and consume resources offline without additional dependencies.
- No legacy schema reader, converter, or automatic remapping. Historical data is not current guidance.
- Every map must reference one canonical OEE revision and carry a draft or reviewed mapping status. Valid JSON is not certification of educational meaning.
- Coverage is mapped, partial, or unmapped. Partial/unmapped require explicit gap explanations. Verified mapping claims need independent edition, section, or authoritative website checks.
- Catalogue IDs are stable and reusable, with optional resource-specific lesson, outcome and assessment references. References must exist in the exact selected OEE Toolkit export.
- Paid resources are always optional; no public OEE requirement depends on paid books, private 0xNAND content or proprietary services.

## Editorial status
## Validation

Each module has a `coverage` value:
Run catalogue checks and tests without a private service:

- `mapped`: reviewed anchor material exists, but not necessarily every lesson is independently covered.
- `partial`: known gaps or important references remain unverified.
- `unmapped`: no usable material has yet been identified.
~~~sh
python3 scripts/check-resources.py
python3 -m unittest discover -s tests -p 'test_*.py' -v
python3 scripts/render-resource-guides.py --check
~~~

Every mapping entry has a separate `verification` value of `verified` or `review-needed`. A title or range inherited from private Content is **not verified** merely because it was previously mapped. Never invent chapter/page numbers or source URLs, and record edition differences.
For a newly reviewed v2 map and an independently generated pinned OEE Toolkit export, use:

`reference`, `practice`, and `optional` are resource recommendation roles; none imposes a paid-book requirement. The goal is adequate, freely accessible study and hands-on material for independent learners.
~~~sh
python3 scripts/check-resources.py --course SEF1 --export /path/to/pinned-SEF1-export.json
python3 scripts/render-resource-guides.py --course SEF1 --export /path/to/pinned-SEF1-export.json --stdout
~~~

## Validate

With a sibling OEE checkout:

```bash
python3 scripts/check-resources.py --oee ../open-engineering-education
```

The validator will check catalogue identities, all resource pointers and mapping correspondence to the actual OEE module and lesson titles. The OEE source revision is recorded for provenance, not used to reject unrelated curriculum changes; structural drift fails validation.

## Generated course guides

- [Browse the SEF1 study guide](guides/SEF/SEF1.md).
- Regenerate public guides with `python3 scripts/render-resource-guides.py --write`.
- Check committed guides with `python3 scripts/render-resource-guides.py --check`.
- Print a course with `python3 scripts/render-resource-guides.py --course SEF1 --stdout`.

These public guides are deterministic snapshots derived from the catalogue and mappings. Do not edit generated guides directly; change the source records and regenerate. The course generator creates a `notes/SEF/SEF1/reading-plan.md` snapshot when a map exists, while the personal `resources.md` reading log remains separate. Existing learner directories are never overwritten. Courses without mappings can still be created, but receive no reading plan yet.
The export consumer checks source identity, module/lesson locators and outcome/assessment references. The caller must independently prove that the export was derived from the named Git commit; a JSON claim alone is not cryptographic provenance. Source lookup and end-to-end binding remain WS-I01; editorial resource review is WS-I02; safe final publishing and regeneration are WS-I04. A map presented without its pinned export **fails closed as source_missing**. No new course guide has yet been accepted.
Loading
Loading