mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-17 04:31:55 +00:00
125 lines
7.2 KiB
Markdown
125 lines
7.2 KiB
Markdown
# Delegation Readiness Doctor — Maintainer Review Handoff
|
||
|
||
Generated: 2026-04-23 16:35 CDT
|
||
PR: https://github.com/NousResearch/hermes-agent/pull/14297
|
||
State: **open · mergeable · refreshed onto current main · approval-blocked at 5 `action_required` suites / 0 check runs · 0 reviews · 1 issue comment**
|
||
|
||
---
|
||
|
||
## One-line verdict
|
||
`hermes doctor` now surfaces a config-aware delegation readiness gate; the full broken→ready→delegated-run proof line still holds after replaying the MVP surface onto current `origin/main` (131 tests passing, 0 failures).
|
||
|
||
## Freshness note
|
||
- PR branch was refreshed onto current `main` again at 2026-04-23 16:35 CDT via GitHub update-branch
|
||
- Current PR head SHA: `6bbda6f7a1fdf045001a4ac676871f9607502074`
|
||
- Current PR base SHA: `a0d8dd7ba30c193390c71360e94991f61f4c4ef3`
|
||
- Branch-refresh proof: `starter-kits/delegation-readiness-doctor/artifacts/latest-pr-branch-refresh.md`
|
||
|
||
## Current workflow-approval blocker
|
||
- `starter-kits/delegation-readiness-doctor/artifacts/latest-pr-review-monitor.md` now shows `5` GitHub Actions check suites, `0` check runs, combined status `pending`, and `1` issue comment
|
||
- `starter-kits/delegation-readiness-doctor/artifacts/latest-workflow-approval-brief.md` records the exact `action_required` suite IDs / API URLs for the current refreshed head after branch update
|
||
- `starter-kits/delegation-readiness-doctor/artifacts/latest-workflow-approval-trigger.md` now packages the current live-state maintainer nudge reference plus direct PR/checks/action surfaces for refreshed head `6bbda6f7a1fdf045001a4ac676871f9607502074`
|
||
- `starter-kits/delegation-readiness-doctor/artifacts/latest-workflow-approval-state-change.md` carries the prior-vs-current blocker state so the next approval or CI-start transition is machine-detectable instead of another snapshot comparison
|
||
- `starter-kits/delegation-readiness-doctor/artifacts/latest-ci-result-interpreter.md` is the fail-closed first-CI decision surface once workflows are approved; until then it proves that the blocker is still approval rather than a hidden test failure
|
||
- Honest interpretation: the PR is waiting on maintainer workflow approval for the refreshed forked head before CI can actually start, not on more local proof work
|
||
- Exact next move: keep the refreshed approval packet aligned to head `6bbda6f7a1fdf045001a4ac676871f9607502074`, then rerun `bash starter-kits/delegation-readiness-doctor/scripts/emit-pr-review-monitor.sh` and `bash starter-kits/delegation-readiness-doctor/scripts/emit-ci-result-interpreter.sh` as soon as a real check run or review appears; if a failing run appears, answer that concrete failure directly from the proof artifacts below instead of treating the PR as approval-blocked
|
||
|
||
---
|
||
|
||
## What this PR does
|
||
|
||
| File | Delta | What it proves |
|
||
|------|-------|----------------|
|
||
| `tools/delegate_tool.py` | −566 / +328 lines | Stubbed `check_delegate_requirements()` replaced with config-aware readiness gate; `get_delegate_readiness_status()` added |
|
||
| `hermes_cli/doctor.py` | +52 lines | Canonical `◆ Delegation Readiness` section in `hermes doctor` output |
|
||
| `tests/tools/test_delegate.py` | −784 / +6 lines | Focused tests for the readiness helper: available/unavailable paths with override resolution |
|
||
| `tests/tools/test_delegate_credentials.py` | new (54 lines) | Credential-aware delegation tests |
|
||
| `tests/hermes_cli/test_doctor.py` | +39 lines | Doctor section output tests: ready and blocked states |
|
||
| `starter-kits/delegation-readiness-doctor/` | new kit | Self-contained proof artifacts and scripts |
|
||
|
||
**Net:** `+1030 / −1831` across 18 files on `main ← hermes/delegation-readiness-doctor-clean`.
|
||
|
||
---
|
||
|
||
## Proof chain (in order of execution)
|
||
|
||
### 1. Gap confirmation (historical — now closed)
|
||
`bash starter-kits/delegation-readiness-doctor/scripts/verify-current-gap.sh`
|
||
- Was the kickoff verifier for the original unconditional-stub gap
|
||
- Now exits non-zero — honest evidence the stub is fixed
|
||
|
||
### 2. Live doctor surface
|
||
```bash
|
||
python -m hermes_cli.main doctor
|
||
```
|
||
Output includes:
|
||
```
|
||
◆ Delegation Readiness
|
||
✓ Delegation ready (override resolves successfully via minimax)
|
||
```
|
||
|
||
### 3. Broken-state roundtrip (isolated — real `~/.hermes/config.yaml` untouched)
|
||
`bash starter-kits/delegation-readiness-doctor/scripts/prove-broken-state-roundtrip.sh`
|
||
- Creates temporary `HERMES_HOME` with bad delegation config
|
||
- Confirms doctor reports `⚠ Delegation blocked`
|
||
- Clears override → confirms doctor flips to `✓ Delegation ready`
|
||
- Emits: `starter-kits/delegation-readiness-doctor/artifacts/latest-broken-state-roundtrip.md`
|
||
|
||
### 4. Clean-worktree verification (definitive proof)
|
||
```bash
|
||
pytest -q -n0 tests/tools/test_delegate.py tests/tools/test_delegate_credentials.py tests/hermes_cli/test_doctor.py
|
||
```
|
||
Run in a detached worktree overlaid only with the PR file set:
|
||
```
|
||
131 passed, 1 warning in 3.32s
|
||
```
|
||
Full output in: `starter-kits/delegation-readiness-doctor/artifacts/latest-clean-commit-surface.md`
|
||
|
||
---
|
||
|
||
## Live delegated-run proof
|
||
A real `delegate_task` call from the ready environment returned:
|
||
```
|
||
READY: delegation executed successfully
|
||
```
|
||
Confirmed in: `starter-kits/delegation-readiness-doctor/artifacts/latest-ship-review.md`
|
||
|
||
---
|
||
|
||
## What is NOT in this PR
|
||
- No credential orchestrator redesign
|
||
- No delegation UX overhaul
|
||
- No multi-provider credential cleanup
|
||
- No dashboard/control-plane additions
|
||
|
||
Scope is intentionally narrow: prove delegation readiness is observable, fail-closed, and repairable before trusting delegated work.
|
||
|
||
---
|
||
|
||
## Immediate maintainer action checklist
|
||
|
||
- [ ] **Review** — skim `tools/delegate_tool.py` diff (readiness gate) and `hermes_cli/doctor.py` diff (output section)
|
||
- [ ] **Verify locally** — run `python -m hermes_cli.main doctor`; confirm `◆ Delegation Readiness` appears
|
||
- [ ] **Verify locally** — run `bash starter-kits/delegation-readiness-doctor/scripts/prove-broken-state-roundtrip.sh`; confirm `BROKEN_STATE_ROUNDTRIP_PROVED`
|
||
- [ ] **Verify locally** — run `pytest -q -n0 tests/tools/test_delegate.py tests/tools/test_delegate_credentials.py tests/hermes_cli/test_doctor.py`; confirm 131 pass
|
||
- [ ] **Merge** if all above hold
|
||
|
||
---
|
||
|
||
## Artifact index
|
||
|
||
| Artifact | Role |
|
||
|----------|------|
|
||
| `latest-readiness-proof.md` | Readiness gate implementation proof |
|
||
| `latest-broken-state-roundtrip.md` | Blocked→ready→proved roundtrip |
|
||
| `latest-ship-review.md` | Shipping decision (SHIPPABLE_ON_PROVED_LINE) |
|
||
| `latest-clean-commit-surface.md` | Clean-worktree overlay + 95-test pass |
|
||
| `latest-pr-review-monitor.md` | Live GitHub API PR state (this PR) |
|
||
| `latest-ci-result-interpreter.md` | First-CI decision surface; fail-closes until real check runs exist and then routes pass/fail signals back to proof |
|
||
| `latest-workflow-approval-brief.md` | Exact `action_required` suite evidence + maintainer approval move |
|
||
| `latest-workflow-approval-trigger.md` | Ready-to-post maintainer nudge + direct PR/checks/action surfaces |
|
||
| `latest-current-gap-report.md` | Historical gap baseline (superseded) |
|
||
|
||
---
|
||
|
||
*This brief is the blocker-specific artifact for the upstream-review stall. It maps every changed file to concrete proof and gives a maintainer a complete approve-or-reject decision path without hunting through CI configs or multiple scripts.*
|