feat(kanban): add review-required as a first-class block kind (AKS-09C)

[dolbabot]

Summary

AKS-09D (corrected AKS-09C): promote the long-standing review-required convention — an un-typed kanban_block whose reason is prefixed "review-required: " — into a first-class typed block kind, on the exact installed v0.19.0 source line.

Fork-only. Base is vendor/installed-v0.19.0-d7b36070 (the exact installed commit), not NousResearch/hermes-agent. Manual human merge only.

⚠️ Correction notice. The original AKS-09C version of this PR was based on cbc1054e under the false claim that the installed source was "cbc1054e + 1 carried commit." That was wrong: cbc1054e is 371 commits ahead of the installed d7b36070, so that base would have pulled 372 commits of unreviewed runtime upgrade into the install. This PR has been rewritten (base + head replaced) to sit directly on d7b36070. The old head a4166d37 was discarded via --force-with-lease.

🟢 Attribution fix (AKS-09E). The single commit has been amended (metadata-only, tree unchanged at 4ff1a93b) to use the accepted GitHub noreply identity dolbabot <180699676+dolbabot@users.noreply.github.com>. The prior author email pilot@dolba-foundry.local was not in the fork's contributors/emails/ registry, causing a check-attribution CI failure that is now resolved.
🟢 CI-control commit (AKS-09F). A second commit (fix(ci): use exact PR base SHA in contributor attribution check) corrects .github/workflows/contributor-check.yml to derive the scan range from the actual PR base SHA instead of hardcoded origin/main. The caller (ci.yml) now passes github.event.pull_request.base.sha as an explicit input. The fix preserves all existing behavior for main-targeting PRs, validates the base is a real commit and ancestor of HEAD (fail-closed), and still catches genuinely unmapped emails introduced by the PR. The prior check-attribution failure was caused by scanning unrelated commits from fork main when the PR targets a vendor branch.

Corrected source identity (verified against full, unshallowed history)

Item	Value
Installed runtime	Hermes Agent v0.19.0 (2026.7.20), git install
Executable	/home/dolbabot/.local/bin/hermes
Source repo	/home/dolbabot/.hermes/hermes-agent (clean)
Installed HEAD	d7b36070ef807841699ad32c5b6af547fee3ff64
PR base branch / SHA	vendor/installed-v0.19.0-d7b36070 @ d7b36070ef807841699ad32c5b6af547fee3ff64
PR head branch / SHA	feat/aks-09c-review-required-kind @ acde2033aa91387a08a0d9b23d7e49f4b0961e9a
Commits in PR	2 (1 runtime patch + 1 CI-control)

Why the prior identity was wrong

The install clone was shallow. origin/main sat at a shallow-grafted boundary commit, so git rev-list --count origin/main..HEAD returned 1 — counting only the fabricated graft edge, not real history. merge-base --is-ancestor also returned false on the truncated DAG, misleadingly suggesting the install had diverged. I incorrectly concluded "installed = cbc1054e + 1 carried commit." After git fetch --unshallow, the true relationship is unambiguous:

merge-base(d7b36070, cbc1054e)          = d7b36070        → d7b36070 IS an ancestor of cbc1054e
rev-list --count d7b36070..cbc1054e     = 371             → cbc1054e is 371 commits AHEAD
rev-list --count cbc1054e..d7b36070     = 0
merge-base(PR head, PR base)            = d7b36070        → PR sits exactly on installed source
rev-list --count d7b36070..PR head      = 2               → exactly two commits (runtime patch + CI-control fix)
cbc1054e is-ancestor-of PR head         = NO              → no unrelated upstream commits
a4166d37 (old head) is-ancestor-of HEAD = NO              → old base fully discarded

What changed (minimal, on exact d7b3607)

review-required joins the canonical block-kind set as a sticky workflow handoff to a human reviewer:

• hermes_cli/kanban_db.py — added "review-required" to VALID_BLOCK_KINDS (+ comment block); documented it in block_task's docstring. Inherits the "truly-blocked" routing (lands in blocked, recurrence-counted) exactly like needs_input/capability — sticky by construction, no special-case code.
• tools/kanban_tools.py — added "review-required" to the model-visible KANBAN_BLOCK_SCHEMA kind enum + description.
• hermes_cli/kanban.py — documented the new kind in block --kind help.
• agent/prompt_builder.py — KANBAN_GUIDANCE now points workers at the first-class kind="review-required" form.
• Docs — kanban.md (tool table + blocked event table) and kanban-worker-lanes.md (convention note).
• Tests — new tests/hermes_cli/test_kanban_review_required_kind.py; two regression tests in tests/tools/test_kanban_tools.py.

Behavior contract

Property	review-required
Member of VALID_BLOCK_KINDS	✅
In model-visible schema enum	✅
Persists kind + reason byte-for-byte	✅ (no normalization)
Routes to blocked (not todo)	✅
Sticky — no auto retry/requeue/promote/unblock	✅ (recompute_ready/_has_sticky_block leave it alone)
Participates in unblock-loop breaker	✅ (same-kind re-block → triage)
In _GOAL_MODE_BLOCK_ALLOWED_KINDS	❌ deliberately excluded — a goal-mode worker must not escape the completion judge via a review handoff

Existing dependency/needs_input/capability/transient behavior unchanged; unknown kinds still rejected.

Schema before / after

# before (d7b36070)
VALID_BLOCK_KINDS = {"dependency", "needs_input", "capability", "transient"}
schema enum       = ["dependency", "needs_input", "capability", "transient"]

# after (PR head)
VALID_BLOCK_KINDS = {..., "review-required"}
schema enum       = [..., "review-required"]
goal-mode gate    = ["dependency", "needs_input"]   # unchanged

Validation on the exact d7b3607 base (real, reproducible)

Test env: isolated venv at the worktree, pip install -e ".[dev]", HERMES_HOME=$(mktemp -d). Live install untouched.

Direct tool invocation (real _handle_block):

status= blocked  kind= 'review-required'
event.kind= 'review-required'  reason= 'PR #9 needs sign-off'   # byte-for-byte, unchanged
bogus-kind -> kind must be one of ['capability', 'dependency', 'needs_input', ...]
ALL_DIRECT_CHECKS_PASS

Targeted + nearest complete Kanban suites (on d7 base): 433 passed, 0 failed

tests/hermes_cli/test_kanban_review_required_kind.py   (new, 7 tests)
tests/hermes_cli/test_kanban_block_kinds.py
tests/hermes_cli/test_kanban_blocked_sticky.py
tests/hermes_cli/test_kanban_db.py
tests/hermes_cli/test_kanban_cli.py
tests/tools/test_kanban_tools.py
tests/hermes_cli/test_kanban_goal_mode.py

Broad kanban suite (pytest tests/hermes_cli/ -k kanban): 16 failed on the feature branch. The identical command + environment run on pristine d7b36070 produces the identical 16-failure set (diff of sorted FAILED lists is empty). These are pre-existing timing/parallelism flakes (test_kanban_db.py stale-claim, test_kanban_decompose.py LLM-fanout, test_kanban_lifecycle_hooks.py) unrelated to block-kind routing; all 3 files pass in isolation (245 passed) on the feature branch. This comparison is reported separately as required and does not mask any failure introduced by this change — none were introduced.

Lint / type / format:

• ruff check (CI-blocking gate): All checks passed!
• git diff --check: clean.
• ty check: zero new diagnostics in every changed source file (identical pristine/feature counts: kanban_db 7=7, kanban.py 21=21, kanban_tools 0=0, prompt_builder 3=3); new test file 0 errors.

Changed files (8 runtime + 2 CI-control)

agent/prompt_builder.py                              |   2 +-
hermes_cli/kanban.py                                 |   4 +-
hermes_cli/kanban_db.py                              |  16 ++-
tests/hermes_cli/test_kanban_review_required_kind.py | 134 ++++  (new)
tests/tools/test_kanban_tools.py                     |  32 ++
tools/kanban_tools.py                                |   4 +-
website/docs/user-guide/features/kanban-worker-lanes.md |  2 +-
website/docs/user-guide/features/kanban.md           |   4 +-

Installation preserves the installed source line

Installing the reviewed head is now a narrow, two-commit patch over the exact installed d7b36070 — no unrelated upstream commits, no runtime upgrade. merge-base(PR head, PR base) = d7b36070; head is now 2 commits ahead (1 runtime + 1 CI-control). Reproducible via git fetch <fork> acde2033aa91387a08a0d9b23d7e49f4b0961e9a && git checkout <sha> && pip install -e ".[dev]". Not performed here.

Corrected CI state (AKS-09F)

GitHub Actions on the retargeted PR: in progress at time of body update (mergeable: MERGEABLE, mergeState: UNSTABLE while checks run). The blocking Python gates are ruff enforcement (passing locally) and the Python test slices (the broad-suite flakes above are pre-existing on pristine d7b36070).

Explicit non-actions (per AKS-09D scope)

Not installed; no live Hermes files edited; no Hermes/gateway restart; no worker/canary run; AKS-09A not resumed; Foundry/Foundry Controller/Preflight policy untouched; this PR not merged; baseline-control smoke PRs NousResearch#6/NousResearch#7 untouched; no second PR opened.

Manual human merge only.

CI-control commit (additional, metadata-only)

 .github/workflows/ci.yml                |  2 ++
 .github/workflows/contributor-check.yml | 34 ++++++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)