SecondBrain/reference/planka-backlog-routing-discoverability-gap.md

type	title	summary	tags	scope	date	last_updated	related
reference	Planka backlog routing is not discoverable by agents — needs project-level pointers and evals	Observed failure (2026-07-10): an agent asked to file cc-os work items defaulted to Forgejo/tea because cc-os's own docs still name Forgejo as the tracker and nothing in any project routes agents to the Planka board — the Planka-vs-Forgejo routing rule, doc-hygiene ownership of CLAUDE.md budgets, and the eval work needed to close the gap.	type/reference tool/planka project/cc-os domain/task-management	global	2026-07-10	2026-07-10	vault-backlog-pilot-plan planka-v2-api-gotchas claude-md-budget-linter-plugin-concept claude-code-hook-lifecycle-injection-capability

Planka backlog routing is not discoverable by agents

The observed failure (2026-07-10)

Asked to file four cc-os work items as "issues," the agent proposed Forgejo via tea — not the Planka board. The user had to redirect. Root causes, all verified:

1. cc-os's own docs/issue-workflow.md still says "Issues live on Forgejo … use tea" — it predates the Planka pilot and was never updated.
2. No project-level pointer exists anywhere (cc-os CLAUDE.md, umbrella CLAUDE.md, injected context) telling agents the Planka board is the work tracker. The routing rule lives only in vault-backlog-pilot-plan — vault knowledge an agent only finds if it thinks to query the vault about task management.
3. The documented routing rule itself is ambiguous in practice: the pilot plan says "Forgejo = code/arch/deployment work inside a repo; Planka = everything else," yet the user routed repo code work (plugin refactors) to the cc-os Planka board. The de facto rule appears to be Planka = the work tracker; Forgejo issues = execution artifacts when a coding session wants them — but this has never been stated crisply anywhere.

What filing on Planka actually takes (verified working)

• Creds: ssh ovh-vps "cat ~/services/planka/bot-credentials.env" → PLANKA_BASE_URL, PLANKA_USERNAME, PLANKA_PASSWORD.
• CLI: cd ~/dev/ruby-gems/planka && bundle exec ruby exe/backlog add --quick "title" --board cc-os --list Backlog --priority p1 (backlog is not on PATH; gem not installed).
• add --quick takes no description — patch it in afterward via client.cards.update(id, description: md).

Action needed (user-stated, 2026-07-10)

Run evals on the Planka board integration to ensure all projects know how and when to use it. Concretely: given a session in any project where the user asks to "file issues" / "track this work," does the agent (a) route to the correct Planka board, (b) apply the Planka-vs-Forgejo rule correctly, (c) find credentials and the CLI without user help? Until project-level pointers (likely the planned os-backlog plugin + per-project CLAUDE.md lines) exist and evals pass, agents will keep defaulting to whatever tracker a repo's stale docs name.

Also stale and needing update once the rule is settled: ~/dev/cc-os/docs/issue-workflow.md.

Related routing decisions made the same session

• CLAUDE.md budget management belongs to os-doc-hygiene, not to the context-injection plugin: the claude-md-budget-linter-plugin-concept should be built as part of the os-doc-hygiene plugin. Managing CLAUDE.md is that plugin's responsibility.
• Injected session-context prompts count toward the effective CLAUDE.md instruction budget — doc-hygiene runs should at minimum note the injected-prompt total alongside CLAUDE.md length (the os-context composer enforces its own injection cap; doc-hygiene owns the whole-budget view).