feat(kanban): allow orchestrator-only graph mutation policy

[jkobject]

Summary

• add kanban.worker_graph_mutations to the canonical hermes_cli/config_defaults.py Kanban hierarchy, defaulting to the existing permissive behavior
• when disabled, hide kanban_create / kanban_link from dispatcher-scoped workers and enforce the same policy again in both mutation handlers
• derive Kanban prompt guidance from the tools actually exposed, including the rare agent_init bypass fallback; restricted workers use followup-request: comments
• retain graph mutation for unscoped orchestrator profiles with toolsets: [kanban]
• document the setting and its current config.yaml location

Observable behavior

Existing installs are unchanged by default. Setting:

kanban:
  worker_graph_mutations: false

prevents dispatcher-scoped workers from creating cards or adding dependency links. The schemas are absent, direct handler bypasses are rejected without DB mutation, and worker guidance names the sanctioned followup-request: path. Human CLI/dashboard actions and unscoped Kanban orchestrator profiles remain unaffected.

No config migration/version bump is required: the public key path remains kanban.worker_graph_mutations; only the stale source location was corrected after DEFAULT_CONFIG moved to hermes_cli/config_defaults.py.

Verification

• scripts/run_tests.sh tests/tools/test_kanban_tools.py tests/tools/test_kanban_redaction.py tests/tools/test_kanban_comment_injection.py tests/agent/test_prompt_builder.py tests/hermes_cli/test_config.py tests/hermes_cli/test_kanban_core_functionality.py tests/hermes_cli/test_kanban_review_surfaces.py tests/hermes_cli/test_kanban_worker_spawn_toolsets.py — 212 passed, 0 failed, 2 skipped
• python -m ruff check ... — passed
• python -m py_compile ... — passed
• git diff --check — passed
• independent pre-commit review — passed after fixing the prompt fallback it identified

Rebased onto origin/main@c0106e50e7ecedb3ce34e785d949725dc4e0e457; contributor head: 52318200993f9c771077a16f1ae31f4bff0a3396.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[alt-glitch]

This was generated by AI during triage.

Related to #30022, #30299, and #66850: this is a configurable current-main implementation of the same orchestrator-only graph-mutation direction. Those prior attempts are closed, so this remains a fresh related submission rather than a duplicate.

[jkobject]

Final reconciliation verification at combined candidate 4e45d6bb870ac9e9e0c01463dd8a9838c92fe19e:

• all changed-scope suites passed (Kanban freeze 679; Supermemory 89; graph policy/prompt/config 464)
• Ruff, py_compile, git diff --check, isolated --version, and isolated doctor passed
• the broad scripts/run_tests.sh run discovered ~40,584 tests; 51 failures occurred in 15 unrelated platform/environment files
• the exact 15-file subset was rerun with -j 1 on both the candidate and clean origin/main@e89bc58a; both produced the identical 51 failures, so the broad-run reds are baseline/environment failures rather than regressions in this PR

No deployment or merge was performed.

[teknium1]

Thanks for the focused policy implementation. The requested configurable behavior is not present on current main: task-scoped workers still receive kanban_create and kanban_link through _check_kanban_mode (tools/kanban_tools.py:92-108, 2131-2155).

Problems

• The config hunk is stale: DEFAULT_CONFIG now lives in hermes_cli/config_defaults.py (hermes_cli/config.py:933) following 1fe06115d1, so the proposed edit to hermes_cli/config.py cannot land as written.
• The added tests exercise handler rejection but not the PR's schema-hiding or prompt-guidance claims. Existing schema coverage is at tests/tools/test_kanban_tools.py:43-63; prompt guidance is fixed during init at agent/agent_init.py:1420-1423.
• The new user-facing setting is absent from the Kanban config table (website/docs/user-guide/features/kanban.md:574-582).

Suggested changes

• Move the default to hermes_cli/config_defaults.py, then add schema, prompt, and documentation coverage for both enabled and disabled modes.

Automated hermes-sweeper review.

[jkobject]

Addressed the live audit on the same contributor branch at 52318200993f9c771077a16f1ae31f4bff0a3396 (rebased onto origin/main@c0106e50e).

Feedback resolution:

• Stale config location: moved the default to canonical hermes_cli/config_defaults.py. The public path remains kanban.worker_graph_mutations, so existing published overrides continue to load without migration or a config-version bump.
• Schema coverage: added positive default-worker and orchestrator cases plus the restricted-worker negative case; restricted schemas omit both kanban_create and kanban_link.
• Runtime authorization: added real-DB tests proving restricted direct handler calls create no task/link, while an unscoped toolsets: [kanban] orchestrator can still create and link.
• Prompt coverage: guidance is derived from the actual tool names at init and in the rare init-bypass fallback. Restricted guidance names followup-request: and contains no instruction to fan out with kanban_create.
• Public docs: added the key, default, YAML example, scope, and enforcement behavior to the current Kanban config table.

Verification: 212 passed, 0 failed, 2 skipped across focused and adjacent Kanban/config/prompt suites; Ruff, py_compile, and git diff --check passed. An independent pre-commit review found one stale fallback, which was fixed and regression-tested; the second review passed with no blocking findings.

Residual risk: check_fn availability is TTL-cached like all tool registration checks, so changing this setting affects newly assembled/refreshed tool schemas rather than mutating a live session's cached prompt/tool prefix. Handler enforcement reads current config and remains the hard boundary.

[jkobject]

PASS — reviewed immutable revision 52318200993f9c771077a16f1ae31f4bff0a3396.

The opt-in policy is coherent across the canonical default, runtime schema gate, handler enforcement, tool-aware prompt guidance (including init bypass), tests, and public documentation. Existing permissive behavior remains the default; restricted workers cannot create/link even through direct handler calls, while unscoped Kanban orchestrators retain graph mutation.

Evidence: 212 focused/adjacent tests passed (0 failed, 2 skipped); Ruff, py_compile, git diff --check, immutable SHA verification, live thread review, and a clean merge-tree against current origin/main@936dd7346 all passed. No blocking findings.