# Technical Implementation Guide for Hermes

## Preflight commands and evidence

Use tools available in the target environment; do not invent command success. At minimum record:

- release-manifest and SHA-256 verification;
- runtime and package-manager versions;
- source tree, application entry points and current tests;
- port availability and loopback behavior;
- Hermes version/profile-safe status and capability endpoints actually supported;
- current worktree/uncommitted changes;
- operating system/architecture; and
- required dependency downloads awaiting approval.

Create a new work copy outside the immutable `source/` directory. If Git is available, use a dedicated branch or worktree and commit intentionally. Do not initialize a repository over unrelated user files.

## Expected reproducible commands

The finished application must document and implement commands equivalent to:

```text
install locked dependencies
initialize or migrate database
seed safe starter content
run development mode
build production assets/server
start production local service
run unit tests
run integration tests
run end-to-end/accessibility tests
run diagnostics/doctor
create backup
validate and restore backup
package release
```

Exact command names follow the selected package manager. No successful path may depend on undocumented source edits.

## Required configuration names

Start from the root `.env.example`. The final `.env.example` contains names and safe comments only. Populate the private `.env` outside source control. Never print values in reports. Separate the application access secret, session secret, CSRF secret and provider keys.

`APP_ACCESS_SECRET`, if the approved architecture actually needs it, is internal server entropy—not a login password, bypass account, universal credential, URL token or browser value. The user creates the local login credential interactively on first run, and only its reviewed password verifier persists. Remove an unused secret variable rather than inventing a second authentication path.

Do not assume the illustrative `HERMES_BASE_URL` from the master contract exists. Detect the installed interface, show the exact proposed local URL and obtain approval before probing it. Do not expose a local gateway publicly.

## Definition of a completed offline core

S1 can pass only when a test proves:

1. first run creates a credential and approved Mission Profile;
2. role-specific Starter missions are clearly labeled;
3. mission/project/task/note/measure/decision/risk/review CRUD works;
4. valid loop transitions and invalid transitions are enforced server-side;
5. material earlier edits reopen downstream stages and clear stale approvals;
6. archive, restore and delete behave distinctly;
7. search/filter/sort operate on real saved records;
8. restart recovers the exact durable state;
9. starter clear/restore never overwrites adopted or real records;
10. export/import/backup/restore/delete validate atomically;
11. role and data partitions reject cross-boundary access;
12. browser code contains no provider secret; and
13. AI controls show a truthful setup/offline state.

## Definition of a connected AI path

S3 can pass only when authenticated capability discovery selects a real supported endpoint and a safe request produces provider-originated streamed deltas. Verify Stop/cancel, retry/failure, session resume, selected-agent server instructions, tool-event separation, redacted diagnostics and no fake fallback. Preserve a sanitized run receipt without confidential content.

If live Hermes is unavailable, finish the adapters and test contracts but report the live path untested. Never relabel a test double as a real smoke test.

## Uniform governance enforcement

Implement one server-authoritative policy engine called by every create/update/import/AI/retrieval/memory/export/agent/tool path. The browser may provide early warnings, but server rules are controlling. Test equivalent actions through different pages and agents to prove the same EDENA, FRAME, TRACE, PROBE, ORBIT, active-hat, data-class and partition result.

Use exactly Green, Yellow, Orange, Red and Unclassified. In the Personal Edition, EDENA advises otherwise allowed sandbox work: an acknowledged Red request may open only an allowed synthetic/abstract hypothetical, simulation or draft. In the Institutional Edition, Red is a mandatory stop. In both editions, prohibited data/actions, live safety issues, expired authority, cross-partition access and `PERM-P4` remain hard stops that acknowledgment or approval cannot override. Neither edition allows the sandbox to claim formal research, regulatory, privacy, legal, clinical, funding or operational approval.

Reject prohibited participant-, patient-, personnel-, confidential-study-, safety-, integrity-, sponsor-, IP-, contract-, grant-, budget-, security- and secret-bearing inputs before persistence. The rejection path must not copy the offending content into logs, exceptions, analytics, memory, badge evidence, exports or receipts.

## Canonical route and partition enforcement

Use lane `healthcare_research_innovation_leadership` and namespace `research_innovation_discover.*`. Serve the canonical dashboard only at `/healthcare-research-innovation-leaders/dashboard`, with `/healthcare-research-innovation-leaders/mission-control` as its sole alias. The lane root `/healthcare-research-innovation-leaders` may only perform a verified redirect to the canonical dashboard. Do not register global dashboard aliases. Enforce tenant governance, portfolio, evidence, sandbox and controls partitions server-side. The optional owner-private partition must use separate consent, encryption scope, export policy and deletion controls; organizational roles and parent Mission Control may not query or infer its existence or content.

## Pinned control and test inventory

Preserve exactly six DISCOVER groups, 24 powers, 24 workflows, 30 templates, 18 independently compiled closed schemas, ten P0 agents and the 160 canonical release criteria. Reconcile the packaged UI/API to all 171 unique control-matrix rows and execute their 171 tests plus 40 cross-cutting scenarios. With the canonical suite, the release owns 371 required execution records. They begin `Not Run`; source presence, implementation status and prior evidence do not pass them.

## Release hygiene

Before packaging:

- scan source/builds/logs/fixtures/reports for secrets and prohibited data;
- run type/build/lint/test commands;
- verify clean install from the packaged archive in a new temporary directory;
- verify migration from the prior supported schema and rollback from failure;
- verify launchers and loopback-only binding;
- verify control matrix coverage against the rendered UI;
- create SBOM, manifest and checksums after all content is final; and
- ensure ZIP members have one safe root, no traversal, symlinks, duplicates or embedded secrets.

The final report records actual results and remaining blockers, not intentions.
