docs: design adaptive pedagogy plugin #2

Merged

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

2026-08-28 04:43:33 +00:00

crowbot commented

2026-08-28 04:17:41 +00:00

Collaborator

Summary

technical design for the requirements merged in #1
revised after a footgun review against requirements.md and the local Hermes checkout (~/.hermes/hermes-agent)

Key decisions

Context bridge: dashboard/plugin_api.py is loaded by _mount_plugin_api_routes with no PluginContext; runtime.py stores ctx from register(ctx) and get_ctx() lazily runs discover_plugins(), failing closed with backend_not_registered if unset.
Async operations for every model/research-bound route (202 + poll), idempotency keys, per-course locks, If-Match revisions, 60 s retry; sync web_search_tool runs in a thread.
Storage: per-course events.jsonl (fsync-before-ack) + derived snapshot + transcript files; full-payload events with upcasters; monotonic pass/complete; no quarantine copies (REQ-017).
MC-only v1 with local key grading and defined scoring; redacted projections so keys/rubrics never reach the client.
API gaps closed: interpret-before-create, diagnostic control routes, review suggestions, challenge flow, /health.
Build-then-install: repo is source; scripts/install.py bundles the TS/JSX desktop half with esbuild, lints output against Hermes' single-ESM rules, atomically installs to ~/.hermes/plugins/hermes-learning/.

Review focus

runtime.get_ctx() bridge and the open question on standalone-dashboard discover_plugins() safety
operations/idempotency model
install script contract

Verification

no implementation code; design gate per spec cycle

## Summary - technical design for the requirements merged in #1 - revised after a footgun review against `requirements.md` and the local Hermes checkout (`~/.hermes/hermes-agent`) ## Key decisions - **Context bridge:** `dashboard/plugin_api.py` is loaded by `_mount_plugin_api_routes` with no `PluginContext`; `runtime.py` stores `ctx` from `register(ctx)` and `get_ctx()` lazily runs `discover_plugins()`, failing closed with `backend_not_registered` if unset. - **Async operations** for every model/research-bound route (202 + poll), idempotency keys, per-course locks, `If-Match` revisions, 60 s retry; sync `web_search_tool` runs in a thread. - **Storage:** per-course `events.jsonl` (fsync-before-ack) + derived snapshot + transcript files; full-payload events with upcasters; monotonic pass/complete; no quarantine copies (REQ-017). - **MC-only v1 with local key grading** and defined scoring; redacted projections so keys/rubrics never reach the client. - API gaps closed: interpret-before-create, diagnostic control routes, review suggestions, challenge flow, `/health`. - **Build-then-install:** repo is source; `scripts/install.py` bundles the TS/JSX desktop half with esbuild, lints output against Hermes' single-ESM rules, atomically installs to `~/.hermes/plugins/hermes-learning/`. ## Review focus - `runtime.get_ctx()` bridge and the open question on standalone-dashboard `discover_plugins()` safety - operations/idempotency model - install script contract ## Verification - no implementation code; design gate per spec cycle

crowbot added 1 commit

2026-08-28 04:17:41 +00:00

docs: design adaptive pedagogy plugin 8e6f846428

crowbot added 1 commit

2026-08-28 04:41:53 +00:00

docs: revise pedagogy design after review 0664fd144d

- Bridge PluginContext into plugin_api.py via runtime.py singleton with lazy
  discover_plugins(); drop double profile scoping
- Make model/research-bound routes async operations with idempotency keys,
  per-course locks, If-Match revisions, and 60s retry
- Split storage into per-course event log, derived snapshot, transcripts
- Full-payload events with upcasters; monotonic pass/complete
- Multiple-choice v1 with local key grading; defined scoring semantics
- Redacted read-model projections so keys never reach the client
- Close API gaps: interpret-before-create, diagnostic control, review
  suggestions, challenge flow, health route
- Threshold in plugin-data settings, objectives as single coverage key
- Source tree + scripts/install.py build-and-install flow