docs: task breakdown for adaptive pedagogy plugin #3

Merged

crowmaki merged 2 commits from docs/pedagogy-tasks into main

2026-08-28 05:12:44 +00:00

crowbot commented

2026-08-28 04:52:19 +00:00

Collaborator

Summary

implementation plan derived from the revised design (squash-merged in #2)
14 numbered groups, dependency-ordered, every leaf with Validate + requirement citations
thin vertical slice first (interpret -> create -> list), then diagnostic, syllabus, research/tutor, assessment, desktop, install, dogfood
deferred items numbered: free-response grading, test-out/badges, cross-course research cache

Pre-implementation hardening (`e4d189b`)

A footgun review cross-checked the tasks against the actual Hermes host code (~/.hermes/hermes-agent). Four design-level mismatches were found that no task's own validation would have caught; both tasks.md and design.md are amended to match:

ctx bridge: plugin_api.py is imported by file path as hermes_dashboard_plugin_<name> with no sys.path change, while the Python half loads as the package hermes_plugins.<slug> from plugin/__init__.py. A module-attribute singleton would be duplicated and get_ctx() would fail closed forever. Now a process-global registry keyed by plugin id; plugin_api.py never touches sys.path; discover_plugins() (synchronous, ~150 ms) runs via asyncio.to_thread.
No custom headers: ctx.rest options are { method, body, upload, timeoutMs }. Idempotency-Key/If-Match replaced by idempotency_key/expected_revision in the body (query on DELETE).
Course-less ops: POST /interpretations and the POST /courses replay record now live under <data_dir>/ops/, not courses/<id>/ops/.
threshold_changed: recorded once in settings.json history instead of fanned out to every course log (which would take every lock, bump every revision, and fail on archived/unreadable courses).

Also: PID-stamped course.lock with stale reclaim (crash must not leave a course locked), missing check-answer route added as the sole objective_evidence producer, plugin/__init__.py + plugin.yaml added to the task-0 skeleton, per-feature route modules and tests/test_api_<feature>.py so parallel worktree agents don't collide, synthetic v0→v1 upcaster fixture, TestClient context fixture for background tasks, Hermes-venv interpreter named for tests and install.py --check, --enable shells out to hermes plugins enable, and the desktop half's separate opt-in toggle in Settings → Plugins documented in install and dogfood.

Review focus

task 0 (import bridge + test harness) is now the load-bearing prerequisite; get it right before fanning out
task 2.4 (operations) and 7.x (assessment lifecycle) still carry the most invariant risk
desktop tasks assume the build-then-install bundling from the revised design

## Summary - implementation plan derived from the revised design (squash-merged in #2) - 14 numbered groups, dependency-ordered, every leaf with Validate + requirement citations - thin vertical slice first (interpret -> create -> list), then diagnostic, syllabus, research/tutor, assessment, desktop, install, dogfood - deferred items numbered: free-response grading, test-out/badges, cross-course research cache ## Pre-implementation hardening (e4d189b) A footgun review cross-checked the tasks against the actual Hermes host code (`~/.hermes/hermes-agent`). Four design-level mismatches were found that no task's own validation would have caught; both `tasks.md` and `design.md` are amended to match: - **ctx bridge**: `plugin_api.py` is imported by file path as `hermes_dashboard_plugin_<name>` with no `sys.path` change, while the Python half loads as the package `hermes_plugins.<slug>` from `plugin/__init__.py`. A module-attribute singleton would be duplicated and `get_ctx()` would fail closed forever. Now a process-global registry keyed by plugin id; `plugin_api.py` never touches `sys.path`; `discover_plugins()` (synchronous, ~150 ms) runs via `asyncio.to_thread`. - **No custom headers**: `ctx.rest` options are `{ method, body, upload, timeoutMs }`. `Idempotency-Key`/`If-Match` replaced by `idempotency_key`/`expected_revision` in the body (query on `DELETE`). - **Course-less ops**: `POST /interpretations` and the `POST /courses` replay record now live under `<data_dir>/ops/`, not `courses/<id>/ops/`. - **`threshold_changed`**: recorded once in `settings.json` history instead of fanned out to every course log (which would take every lock, bump every revision, and fail on archived/unreadable courses). Also: PID-stamped `course.lock` with stale reclaim (crash must not leave a course locked), missing `check-answer` route added as the sole `objective_evidence` producer, `plugin/__init__.py` + `plugin.yaml` added to the task-0 skeleton, per-feature route modules and `tests/test_api_<feature>.py` so parallel worktree agents don't collide, synthetic v0→v1 upcaster fixture, `TestClient` context fixture for background tasks, Hermes-venv interpreter named for tests and `install.py --check`, `--enable` shells out to `hermes plugins enable`, and the desktop half's separate opt-in toggle in Settings → Plugins documented in install and dogfood. ## Review focus - task 0 (import bridge + test harness) is now the load-bearing prerequisite; get it right before fanning out - task 2.4 (operations) and 7.x (assessment lifecycle) still carry the most invariant risk - desktop tasks assume the build-then-install bundling from the revised design

crowbot added 1 commit

2026-08-28 04:52:19 +00:00

docs: task breakdown for adaptive pedagogy plugin c9840248bd

crowbot added 1 commit

2026-08-28 05:11:11 +00:00

docs: harden pedagogy plugin design/tasks against verified host constraints e4d189b082

- ctx bridge is a process-global registry; plugin_api.py and the
  hermes_plugins.<slug> package are separate module trees
- idempotency_key / expected_revision travel in body/query (ctx.rest
  has no headers option)
- course-less ops live under <data_dir>/ops/
- threshold_changed recorded once in settings.json, not per course
- PID-stamped course.lock with stale reclaim
- add check-answer route, plugin/__init__.py, plugin.yaml, per-feature
  route modules and test files, Hermes-venv interpreter, opt-in desktop
  toggle, hermes plugins enable