hermes

• What it is: @regain/hermes (hermes_version: 2.0.0) — a reference implementation of the eponymous protocol: standardized messages (supervision_request, supervision_response, control_command_v2, control_command_response, audit_event, clinician_feedback, bias_detection), their types/guards/JSON Schema, plus runtime epistemology utilities (HTV composite, calibrated uncertainty, evidence-grade hierarchy, v1→v2 Control-channel migration). Named after Hermes — the messenger between worlds; here, between the clinical-AI agent and the supervision system. The README positions it as the "industry-standard protocol for safe, auditable clinical AI" with a forthcoming certification program (Compatible / Certified / Certified Clinical).
• Type / status / role: library (npm package, ESM+CJS, dist/ + src/ with conditional exports under Bun) · active / Public Alpha · lead — the user is the primary author (14 of 24 commits = 58%); the US healthtech platform team: Anton Kim <anton@US healthtech platform> (9), Harsh Manwani (1). All phases 1–5 and the npm publication are the user's.
• Activity period: 2026-01-25 → 2026-02-13 — a ~3-week sprint "from zero to npm v1.0.x → v2.0.0", live on the registry. Full OSS scaffolding (LICENSE Apache 2.0, README, VISION, GOVERNANCE, CONTRIBUTING, CODE_OF_CONDUCT, TRADEMARK, CERTIFICATION, CHANGELOG, CI badges).

• Languages: TypeScript 5.7 (strict, ESM-first), JSON Schema (draft-2020-12).
• Frameworks/libraries: Bun (test runner, dev/watch, dual ESM+CJS build via bun build with --format esm and --format cjs); AJV 8 + ajv-formats for runtime schema validation (new Ajv({ allErrors: true, strict: false }) for draft-2020-12 compatibility); Biome 1.9 (lint/format); tsc --emitDeclarationOnly for declarations; a lefthook-style .githooks/pre-commit (prepare runs git config core.hooksPath). Conditional exports in package.json — bun → src/*.ts, import → dist/*.js, require → dist/*.cjs (zero-build DX in Bun projects + classic Node distribution).
• Infra/deploy: GitHub Actions CI (ci.yml badge green); published to npm under access: public on registry.npmjs.org; fix(ci): publish only on version tags (185de71) — releases only on git tags. Homepage/issue tracker — github.com/US healthtech platform/hermes.
• Data: no database (this is a library); it does describe audit-event formats with PHI minimization and AuditRedactionBase for downstream storage.
• Notable tooling: git worktree (hermes-2, hermes-3) used for parallel development of Phases 2 and 3 on the same main branch — a non-trivial workflow initiated by the user (see AI sessions). A trademark bundle (US healthtech platform Hermes™, Popper™, Deutsch™, Hard2Vary™).

24 commits, 5 clearly delineated phases → publication → v2:

• Phase 1 — Core Types (762a1ed +4361/-0, 28 files): branded types, base TraceContext / IsoDateTime / HermesVersion / SubjectRef / ProposedInterventionKind / Mode / SupervisionDecision, type guards.
• Phase 2 — Supervision Contract (5927e52 +2876/-72, in worktree hermes-2): SupervisionRequest/Response, InputRisk (phi_detected, prompt_injection_suspected), PriorOverride, ProposedIntervention, HealthStateSnapshotRef, cross-domain conflicts (CrossDomainConflict, ConflictEvaluation), ConfidenceLevel / OverrideApplicability / RationaleCategory.
• Phase 3 — Epistemology Types (bbdca0c +1959, in worktree hermes-3): ClaimType + risk profiles (diagnosis / treatment_rec / escalation → requiresPopper: true), EvidenceGrade (a 10-level hierarchy from systematic_review down to calculated), HTVScore (Hard2Vary 4D: interdependence/specificity/parsimony/falsifiability), UncertaintyCalibration + UncertaintyDriver. The two worktrees are merged (7eaa0d6, PR #1, PR #2).
• Phase 4 — Clinical, Imaging & Bias Detection (b963693 +2642): imaging.ts (medical imaging), bias.ts (BiasDetectionType: demographic_override_disparity / intervention_type_bias / clinician_specialty_bias — FDA post-market AI/ML surveillance), feedback.ts (clinician feedback with rationale categories), disclosure.ts.
• Phase 5 — Testing, Validation & CI (6f4faa3 +3375): an AJV validator on draft-2020-12, a 1405-line JSON Schema (hermes-message.schema.json), 11 fixture files (sup-request/response, audit-event, clinician-feedback, evidence, htv-score), 41 conformance tests, GitHub Actions, .githooks/pre-commit. package.json exports gained ./schema and ./fixtures submodules.
• npm publication: a977689 chore: prepare for npm publication v1.0.0, b9c3791 chore: remove internal docs and spec references (-2977 lines, cleanup of private PRD/specs before the public release — a textbook pre-publish gate), releases 1.0.0 → 1.0.1 → 1.0.2 → 1.0.3, a6b9c9c chore: change license from MIT to Apache 2.0 (the right choice for clinical software with a trademark strategy).
• **A SAL-* feature pack landed immediately after publish:** c6df831 developer docs (docs/DEVELOPER-GUIDE.md, API-REFERENCE.md, EPISTEMOLOGY-GUIDE.md, TESTING.md), bc3d701 feat(SAL-508): auto-refutation types for Popperian prediction failure, a964697 ControlCommandV2 + Operational Settings Catalog (621 lines of types, 176 lines of tests), 8d082ab v1→v2 builders + migration utilities, 117cc28 AJV schemas + conformance fixtures for Control v2, d017a86 feat: add Control v2 exports, comprehensive tests, and bump to v2.0.0 — a major bump in 3 weeks.
• Volume: 24 commits; 10,901 LOC TypeScript + 1,405 LOC JSON Schema; fully test-covered (*.test.ts next to each module).

By code / diffs:

• Popper/Deutsch epistemology as code (src/types/epistemology.ts, src/utils/htv.ts, src/utils/uncertainty.ts): the protocol codifies the philosophy of science — every clinical claim is classified (observation / diagnosis / treatment_rec / escalation ...), and high-risk types are required to carry falsification_criteria in advocate_clinical mode. The HTV composite (Hard2Vary, after Deutsch): a weighted sum of interdependence × specificity × parsimony × falsifiability; clamped to [0,1] with range validation. Calibrated uncertainty (computeUncertainty): an additive model over 5 drivers (evidence_grade 0–0.3, htv_score 0–0.3, data_quality 0–0.2, debate_consensus 0–0.1, staleness 0–0.1) → low | medium | high. → Demonstrates turning academic epistemology into a working API.
• JSON Schema draft-2020-12 + AJV strict-relax (src/schema/validator.ts): new Ajv({ strict: false }) for draft-2020-12 compatibility; errors are mapped into {path, message}[]; a custom HermesValidationError aggregates the message; a pair of APIs — validateHermesMessage (returns), parseHermesMessage (throws), isValidHermesMessage (type guard). → Sound API design for a library: three runtime contracts on top of one validation.
• Idiomatic TypeScript design: branded types (src/types/branded.ts), readonly-everywhere (DTO-only), as const arrays for runtime enum validation, conditional exports for Bun (zero-build) and Node (ESM+CJS), sideEffects: false for tree-shaking. The Phase 1 diff (+4361/-0) lays the foundation right away with guards and tests.
• Control Channel v2 with migration (src/types/control-v2.ts 239 lines, src/utils/control-migration.ts 192): the move from stringly-typed v1 to fully typed (SettingValue = boolean|string|number|string[]), batched commands, priority-aware (ROUTINE / URGENT / EMERGENCY), idempotency_key, operational modes (NORMAL / RESTRICTED / SAFE_MODE / MAINTENANCE), full state snapshots in the ack. Two-way mapV1ToV2 / mapV2SettingToV1 with autonomy mapping ('0' → 'passive', ...) and a set of removed v1 keys (disable_domain, policy_pack). → A complex but disciplined protocol evolution; behind the SAL-* tickets sits real legacy.
• Bias detection as a first-class message type (src/types/bias.ts 302 lines): BiasDetectionType ('demographic_override_disparity' et al.), BiasSeverity, BiasAnalysisPeriod, BiasDimensionType — aligned with FDA AI/ML post-market surveillance guidance. → A compliance mindset codified, not bolted on.
• A git-worktree workflow for parallel phases (see AI sessions): the user themselves initiated git worktree add hermes-3 for Phase 3, in parallel with hermes-2 for Phase 2, merging via PRs (#1, #2) into main. → Mature git command, atypical for most seniors.
• Pre-publish hygiene: the b9c3791 chore: remove internal docs and spec references commit deleted 2,977 lines of internal PRD/spec material before the public release — a thoughtful gate to keep Healthcare platform-specific details out of the npm tarball. That is commercial-OSS-strategy thinking.

• Sessions found: 5 (-Users-macbookpro-development-hermes/, 133 messages total). Additional sessions inside the hermes-2/3 worktrees are not registered as separate CC projects — they ran through the main hermes directory.
• What was done with AI (per the index's firstPrompt / summary): 1. cf51ad0a — "Study best practices for npm package development with bun.js... create the scaffold" (10 msgs) — package bootstrap. 2. 7853e944 — "@docs/PLAN-01-phase-1-core.md translate all tasks... into a task list" (31 msgs) — Phase 1 (Core Types). 3. eebcdb59 — "Create git worktree hermes-2 and let's switch to working in it" (41 msgs) — Phase 2-3 in the worktree. 4. b7a92f59 — "Create git worktree hermes-3 and let's switch to working in it" (27 msgs) — Phase 3 (Epistemology) in parallel. 5. 0dc63c85 — "@docs/PLAN-04-phase-4-clinical.md break down the tasks... grounded in ...new_unified_health_app/docs/0..." (24 msgs) — Phase 4 (Clinical/Imaging/Bias) with cross-repo context.
• AI workflow patterns: plan-driven (PLAN-XX-phase-X-*.md as a contract), task lists are translated by the agent from markdown into TodoWrite, parallel phase-agents inside git worktrees (one of the headline AI-native moves — multiple work streams in a single repo with no conflicts), cross-repo grounding (Phase 4 leans on specs from new_unified_health_app — the same healthcare monorepo). All 5 phases were executed and shipped in ~3 weeks at high velocity while preserving test coverage and the OSS scaffolding.

• The @regain/hermes npm package in the public npmjs.org registry (Apache 2.0, public alpha), v2.0.0; GitHub US healthtech platform/hermes with a green CI badge.
• 10,901 LOC TypeScript + 1,405 LOC JSON Schema; 41 conformance tests in Phase 5; per-module tests (*.test.ts next to every type / utility).
• 5 phases with up-front architectural planning (PLAN-01..05) shipped in ~3 weeks (24 commits, 14 authored by the user).
• The user is the primary author of the protocol that ties popper (#62/72 user commits, infra/governance), deutsch (reasoning engine), healthcare-crm (product CRM), and lab-processor (Temporal pipeline) into a single US healthtech platform clinical-AI platform.