Nagato Game Assist · Development Infrastructure

Hermes-Native Review Council

A complete implementation plan for evidence-grounded, multi-model GitHub issue deliberation and exact-head PR review using Hermes profiles, Featherless models, the existing shared Valkey concurrency guard, and deterministic Nagato verification.

No new API/serviceReuse Hermes + Featherless credentials and routing.

No core patch for pilotDedicated profiles and one-shot Hermes workers are enough.

Optional core improvement laterPer-task profile routing would make heterogeneous delegation cleaner.

Architecture decision

What we will—and will not—build

Build

An agent-owned nagato-review-council skill.
Four narrowly scoped Hermes reviewer profiles.
A PowerShell-first orchestrator and deterministic Python helpers.
Evidence packets tied to exact Git SHAs.
Independent reviews, targeted challenge, verifier, synthesis.
Preview-first GitHub issue/PR comments.

Do not build

No PydanticAI or Agent Council runtime dependency.
No additional SaaS, API account, daemon, or model key.
No council logic inside the Nagato widget or bridge.
No automatic posting or merging from model opinion.
No all-to-all debate that wastes quota.
No confidence score treated as proof.

Boundary: this is development/review infrastructure. Nagato’s shipped application remains unaware of the council.

Target system

End-to-end architecture

GitHub source
Issue/PR, discussions, checks, exact SHAs

→

Evidence builder
Sanitize, normalize, hash, classify risk

→

3 reviewer lanes
GLM · Kimi · DeepSeek under Valkey lease

→

Finding reducer
Validate, dedupe, detect contradictions

→

Verifier
Source + tests + schemas + exact head

→

Synthesizer
Consensus, disputes, decision requests

→

Preview / GitHub
Explicit posting only

Architecture lane

GLM-5.2

Contracts, compatibility, data authority, architecture boundaries.

Implementation lane

Kimi K2.7 Coder

Call paths, tests, Windows behavior, maintainability.

Adversarial lane

DeepSeek V4 Pro

Security, privacy, deletion, malformed input, migration failure.

Implementation sequence

Detailed step-by-step build plan

Protect current state and open the maintenance slice

Do not modify the existing deleted CODEX_HANDOVER.md or untracked docs/plans/.
Open a private Nagato-branded maintenance issue and include “100% coded by AI/Hermes.”
Capture current Hermes version, carried local commits, profile list, exact Featherless catalog IDs, and shared slot limit—never credentials.
Record baseline review cost and Fable usage for comparison.

Exit: scope, owner, acceptance criteria, rollback, and metrics are written before code.

Define contracts before orchestration

Create JSON Schemas for evidence packet, finding, model attestation, challenge result, and final report.
Require exact base/head SHA and evidence digest in every lane.
Define severities: critical, high, medium, low, note.
Define dispositions: verified, disputed, rejected, stale, human-decision.
Require a concrete evidence pointer for blocking findings.

Exit: invalid, missing-evidence, or wrong-SHA findings fail closed in fixture tests.

Create the agent-owned council skill

Write SKILL.md with triggers for issue decisions, PR review, wave-boundary review, and escalation.
Add role prompt templates; issue/PR text is explicitly untrusted data.
Add review-tier mapping from Nagato AGENTS.md.
Add convergence rule: one challenge round, stop when no new verified evidence appears.
Add Fable as human-triggered escalation only.

Exit: a fresh Hermes session can load the skill and explain the same deterministic lifecycle.

Create dedicated Hermes profiles

Create architecture, implementation, adversarial, and verifier profiles under the active profile-safe Hermes home.
Pin each reviewer to its model; verifier defaults to GPT-5.6 sol or GPT-5.5 med.
Use minimal read-only toolsets for reviewers.
Only the parent/orchestrator receives GitHub write authority.
Load Nagato project context from the exact worktree.

Exit: each profile returns profile name, requested model, observed provider/model, SHA, and packet digest.

Integrate Featherless safely

Resolve exact live model IDs rather than friendly names.
Reuse the existing featherless provider and key.
Acquire the shared Valkey-backed lease before every reviewer model call.
Limit fan-out to three; add bounded timeout and jittered retry.
Reject model-identity mismatch and non-schema output.
Run one structured-output smoke per model before council use.

Exit: monitored concurrent smoke never exceeds the shared slot limit and all identities attest correctly.

Build the PowerShell-first orchestrator

Create commands for IssueDecision and PullRequest, with -DryRun default behavior.
Use gh and git to fetch metadata, checks, files, base/head, and discussions.
Build, redact, canonicalize, and hash the packet.
Launch profile-specific hermes chat -q workers in parallel.
Capture stdout to lane artifacts without exposing secrets.
Validate every artifact before continuing.

Exit: fixture mode runs end-to-end with fake GitHub/provider outputs and produces a valid report.

Normalize, deduplicate, and cross-examine selectively

Group findings by invariant, path, line range, and failure scenario.
Merge duplicates while preserving all supporting evidence and model attribution.
Challenge only high/medium findings, contradictions, and low-confidence blockers.
Send the finding—not the entire debate—to one independent challenger.
Preserve disagreement instead of forcing consensus.

Exit: duplicate findings collapse; unsupported claims become rejected or human-decision, never blockers.

Run deterministic verification

Read full source around each candidate finding.
Verify the worktree import path before tests.
Run focused tests, full pytest, Ruff, Pyright, compile, schemas, security scan, and git diff --check.
Run signed UWP build when widget files changed.
Attach actual command/exit evidence to each validated finding.
Re-fetch PR head after verification.

Exit: stale SHA aborts publication; zero unresolved high/medium findings is required.

Synthesize and render

Produce consensus findings, disputed findings, rejected claims, residual human decisions, and looks-good evidence.
Include exact-head SHA and all implementing/reviewing model identities.
Generate Nagato-branded Markdown for GitHub and local JSON/HTML artifacts.
Default to preview; require explicit -Post.
Never approve or merge merely because the council converged.

Exit: report is traceable from conclusion → finding → evidence → source/test.

Pilot, measure, and gate rollout

Shadow-review one ordinary bridge PR and one high-risk persistence/protocol PR.
Compare with the current Hermes/Codex review and optional manual Fable review.
Measure unique valid findings, false positives, duplicates, duration, and slot use.
Tune prompts from observed errors, not taste.
Enable issue-draft preview, then explicit posting after two clean pilots.

Exit: adoption decision is based on measured review value and stable concurrency.

Operational modes

Two council workflows

GitHub issue decision council

Fetch issue plus accepted prior decisions.
Run product/acceptance, architecture, and adversarial pre-mortem lanes.
Extract contradictions and unanswered product decisions.
Draft recommendation, alternatives, risks, and executable acceptance criteria.
Preview locally; post only explicitly.

Best for architecture, persistence semantics, privacy/deletion, UX trade-offs, and ambiguous acceptance criteria.

Exact-head PR review council

Classify review tier from changed surfaces.
Build packet from exact base/head and full changed-file context.
Run independent lanes.
Challenge serious or disputed findings.
Run fresh deterministic gates.
Re-check head, synthesize, and optionally post.

A review is stale immediately when the PR head changes.

Fail-closed contracts

Required data artifacts

Artifact	Required contents	Why
Evidence packet	Repo identity, issue/PR, base/head SHA, changed files, diff digest, checks, trusted invariants, untrusted discussion	All agents review the same immutable snapshot.
Finding	ID, severity, confidence, path/line, claim, failure scenario, evidence, reproduction, recommendation	Machine validation and deduplication.
Model attestation	Profile, requested model, observed model/provider, start/end time, packet digest	Prevents silent model fallback from satisfying review policy.
Challenge result	Finding ID, agree/disagree, counter-evidence, revised severity	Targeted cross-examination without token-heavy debate.
Council report	Verified, disputed, rejected, stale, decisions, checks, identities, exact head	Auditable GitHub and wave-boundary record.

Verification matrix

Tests and acceptance gates

Unit

Schema validation
Canonical hashing
Redaction
Risk classification
Deduplication
Convergence/stop rules

Integration

Temporary HERMES_HOME
Fake gh and Git
Mock model metadata
Fake Valkey lease
Stale-head abort
Windows paths/quoting

Live manual smoke

One call per Featherless model
Three-lane bounded fan-out
Private synthetic PR
Preview only
Observe slot occupancy
Verify model identity

uv run python -c "import game_assist_bridge; print(game_assist_bridge.__file__)"
uv run pytest tests -q
uvx ruff==0.15.21 check bridge tests
uvx pyright==1.1.411 bridge
uv run python -m py_compile bridge/game_assist_bridge/*.py
git diff --check
# Plus scripts/build-widget.ps1 whenever widget files change

Hermes codebase impact

Does Hermes itself need modification?

Pilot: no

Current Hermes supports profiles, model/provider pinning, one-shot sessions, project workdirs, skills, and concurrent child processes. The pilot can launch hermes --profile NAME chat -q ... for each lane.

This keeps the experiment at the edge, consistent with Hermes’s narrow-waist policy.

Production ergonomics: recommended later

The current delegate_task schema explicitly says its model is not selectable per call; all children inherit one parent/delegation model. A generic optional per-task profile selector would remove subprocess orchestration and expose heterogeneous councils cleanly.

Optional Hermes core change

Add an optional task-level profile field to delegate_task; prefer profiles over raw credential-bearing provider parameters.
Resolve only allowlisted local profiles and reject cross-profile writes by default.
Return observed model/provider identity in result metadata.
Keep max_concurrent_children and provider-level lease enforcement.
Preserve prompt caching, strict role alternation, and isolated context.
Add E2E tests with temporary profile homes and a mocked provider.
Likely surface: tools/delegate_tool.py, config/schema migration, delegation tests, docs.

Recommendation: do not patch Hermes first. Prove the workflow with profiles and one-shot workers, then upstream a generic profile-routing enhancement if the metrics justify it.

Release strategy

Safe rollout ladder

Stage	Behavior	Promotion gate
0 · Fixtures	No live models or GitHub writes	All contracts and failure paths pass
1 · Model smoke	One small structured call per model	Identity + schema + slot compliance
2 · Shadow review	Review real PR, local report only	Useful findings, acceptable false positives
3 · Preview mode	Generate GitHub-ready draft	Two clean pilots
4 · Explicit post	Human invokes `-Post`	No stale SHA, gates green
5 · Standard gate	Risk-tiered council on suitable PRs	Wave-boundary retrospective

Failure controls

Risk register

Technical

Oversubscription: Valkey lease + max-three fan-out.
Wrong model: requested/observed identity mismatch invalidates lane.
Stale review: re-fetch head before synthesis and posting.
Windows quoting: PowerShell integration tests with spaces/native paths.
Hermes updates: carried Featherless patch reapply and doctor check.

Review quality

False consensus: preserve residual disagreement.
Hallucinated defect: evidence required for blockers.
Review loop: one bounded challenge round.
Prompt injection: GitHub content marked untrusted.
Quota waste: challenge findings, not entire transcripts.