docs(kanban): document handoff evidence metadata

[Fearvox]

What does this PR do?

Documents an optional metadata convention for Kanban worker handoffs so humans, downstream agents, and dashboards can read the same evidence packet without scraping prose.

This is intentionally docs-only. The runtime already accepts structured metadata through kanban_complete(summary=..., metadata={...}); this PR only describes a practical shape for engineering/review tasks.

Related Issue

No issue yet; this is a docs-only clarification for existing Kanban behavior.

Type of Change

• Documentation update

Changes Made

• website/docs/user-guide/features/kanban.md
  • Adds a "Recommended handoff evidence" section.
  • Suggests optional keys: changed_files, verification, dependencies, blocked_reason, retry_notes, and residual_risk.
  • Clarifies that these keys are a convention, not a schema requirement.
  • Calls out that secrets, raw logs, tokens, OAuth material, and unrelated transcripts should not be placed in task metadata.

Evidence Checked

• Existing tool surface: kanban_complete already exposes summary and metadata as the structured completion handoff.
• Existing docs already describe Kanban as a durable queue where every handoff is a row any profile or human can read.
• PR hygiene check: feat(state): track per-skill cron invocations + EMA query for labyrinth #19507 was superseded by feat(state): track per-skill cron invocations + EMA query for labyrinth #19508 to keep an unrelated TUI change out of the branch; this PR keeps the diff to one docs file.
• Branch compare: 1 commit, 1 modified file, +34/-0.

How to Test

1. Review the edited docs section in website/docs/user-guide/features/kanban.md.
2. Confirm the example metadata is valid JSON.
3. Confirm the wording does not imply required schema enforcement or runtime behavior changes.

Not run: full website build. This is a docs-only copy change with no code/runtime path touched.

Checklist

Code

• I've read the Contributing Guide.
• My commit message follows Conventional Commits.
• I searched open PRs for duplicate Kanban handoff/evidence metadata work.
• My PR contains only changes related to this docs clarification.
• N/A: pytest tests/ -q is not relevant for a docs-only copy change.
• N/A: tests are not added because runtime behavior is unchanged.
• Tested on my platform: macOS, docs diff review only.

Documentation & Housekeeping

• I've updated relevant documentation.
• N/A: no config keys changed.
• N/A: no architecture or workflow files changed.
• N/A: no cross-platform runtime impact.
• N/A: no tool behavior changed.

Non-goals

• No database schema migration.
• No dispatcher/runtime behavior change.
• No dashboard rendering change.
• No mandatory metadata validation.

Residual Risk

The exact field names may need maintainer vocabulary changes. Because this is docs-only and explicitly optional, the safe review path is to adjust naming here before any tests or runtime UI depend on it.

[Copilot]

Pull request overview

Documents a recommended (optional) metadata convention for kanban_complete(...) handoffs so evidence can be consumed consistently by humans and downstream automation without scraping prose.

Changes:

• Adds a “Recommended handoff evidence” section describing a suggested metadata shape for engineering/review tasks.
• Emphasizes the convention is optional (not a schema requirement) and discourages placing secrets/logs/tokens/transcripts in metadata.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Fearvox]

Follow-up plan, keeping this PR intentionally small:

• This PR only documents an optional handoff convention for existing kanban_complete(..., metadata={...}) behavior.
• The next narrow PR is open as test(kanban): assert metadata handoff round-trip #19522: it adds a fixture proving that completion metadata round-trips through kanban_complete and is readable from kanban_show.
• Dashboard rendering or schema enforcement would stay out of both of these PRs unless maintainers explicitly want that direction.

The goal is to make Kanban handoffs easier for humans and downstream agents to review without changing runtime behavior in the docs PR.