docs(kanban): document kanban.max_in_progress dispatcher cap (from #28420)

[r266-tech]

The kanban.max_in_progress config knob added in #28420 (merged 2026-05-19) doesn't appear in any of the three dispatcher-reference surfaces that already document kanban.failure_limit. New users hitting "running" backlog on slow workers (local LLMs, resource-constrained hosts) have no easy way to discover the new cap.

Changes

• website/docs/user-guide/features/kanban.md (Dispatcher bullet) — append a sentence about kanban.max_in_progress next to the existing failure_limit sentence.
• AGENTS.md (Kanban one-pager) — add a bullet next to the existing failure_limit bullet.
• skills/autonomous-ai-agents/hermes-agent/SKILL.md (Dispatcher bullet) — append a sentence to the existing failure-limit / max_retries block.

Behavior documented

Source of truth: gateway/run.py:4784-4820 (validate_kanban_cfg block).

• Unset is the default — no cap, dispatcher spawns freely.
• Positive integer (N >= 1) → cap how many tasks may sit in running simultaneously; dispatcher skips spawning more when at the cap.
• Non-integer or < 1 → logged as invalid and ignored (treated as unset).

The "ignored when < 1" path matters as an anti-footgun: setting kanban.max_in_progress: 0 looks like "disable spawning" but actually leaves the dispatcher unlimited. Each of the three surfaces calls this out.

Provenance

• kanban.max_in_progress config key + validation: gateway/run.py:4784-4820.
• Original feature PR: feat(kanban): add max_in_progress config to cap concurrent running tasks (#22981) #28420 (feat(kanban): add max_in_progress config to cap concurrent running tasks (#22981), merged 2026-05-19T03:50Z, salvaged from @SimbaKingjoe).
• Sibling existing failure_limit documentation pattern (fix(kanban): heartbeat + reclaim + zombie + retry-cap fixes (#21147, #21141, #21169, #20881) #21183 + feat(kanban): per-task max_retries override (supersedes #20972) #21330 alignment in docs(kanban): align dispatcher failure_limit text with current default (5→2 from #21183, +max_retries from #21330) #21402 / docs(kanban): align dispatcher failure_limit text with current default (5→2 from #21183, +max_retries from #21330) (#21402) #28357) is the template followed here.

If this has already landed via separate patch / hermes-sweeper salvage, please feel free to close and mark accordingly.

[teknium1]

Thanks for the docs cleanup. I verified the premise against current origin/main and the PR is still useful, though one related user-guide surface is now partially covered elsewhere.

Current main has kanban.max_in_progress in the config table at website/docs/user-guide/features/kanban.md:709, including unset/unlimited and invalid/below-1 behavior. But the top dispatcher paragraph still only mentions kanban.failure_limit at website/docs/user-guide/features/kanban.md:69, the AGENTS one-pager still only mentions kanban.failure_limit at AGENTS.md:1090, and the bundled hermes-agent skill still only documents failure_limit / max_retries at skills/autonomous-ai-agents/hermes-agent/SKILL.md:708.

The behavior being documented matches current code: gateway validation warns/ignores non-integer and below-1 values in gateway/kanban_watchers.py:628, and the dispatcher enforces the cap by skipping or limiting spawns in hermes_cli/kanban_db.py:6116.

No blocking issues from this automated hermes-sweeper review.

[teknium1]

Thanks for closing the overview-documentation gap. The premise remains valid on current main: the dispatcher overview at website/docs/user-guide/features/kanban.md:69, the Kanban one-pager at AGENTS.md:1120, and the bundled skill at skills/autonomous-ai-agents/hermes-agent/SKILL.md:791 still omit kanban.max_in_progress.

Problems

• The new wording says non-integer values are invalid, logged, and ignored. Current implementations use int(value) (gateway/kanban_watchers.py:842, hermes_cli/kanban.py:2135) rather than rejecting values by type. Please phrase this as values that cannot be coerced to an integer, or whose coerced value is below 1, being ignored—or make strict integer validation a separate behavior change.

Suggested changes

• Apply that wording correction consistently across all three changed documents.
• The website hunk needs a small manual salvage because its surrounding scratch-workspace context differs from current website/docs/user-guide/features/kanban.md:66; the intended dispatcher paragraph is still at line 69.

Automated hermes-sweeper review.

[teknium1]

Please avoid describing every non-integer value as invalid: the current paths use int(value) (gateway/kanban_watchers.py:842, hermes_cli/kanban.py:2135). Say values that cannot be coerced to an integer, or whose coerced value is below 1, are ignored.