3.5 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0033 | 2026-07-13 | Superseded | 0042 |
|
|
0033 — Tracker routing: Planka is state, git issues are specs
Context
The backlog pilot plan (vault note vault-backlog-pilot-plan.md) originally routed everything to Forgejo issues, later amended informally to "Forgejo = code work in a repo; Planka = everything else." The os-backlog slices then shipped a sharper boundary in practice — encoded in plugins/os-backlog/skills/route/SKILL.md, the /to-issues destination-tracker step (global skill ~/.agents/skills/to-issues/SKILL.md, step 5), and the plugins/os-backlog/hooks/session_start.py injection note — but no ADR canonizes it, so the rule lives only in skill prose and could drift or be silently edited away. This ADR records already-implemented practice; it does not introduce new behavior.
Decision
Canonize the tracker-routing boundary, amending the pilot plan's "Forgejo for everything" rule. (1) Boundary rule: Planka = task STATE (backlog/next/doing/waiting/review/done — what's happening now); git issues = durable SPECS (text that must survive and be referenced: features, migrations, architecture-level work, tracer-bullet slices from /to-issues, PRDs); repo:<path> is the escape hatch for projects that already track issues in-repo and want to stay there. (2) Each project declares exactly one destination via the tracker key in .cc-os/config, grammar: planka:<board> | forgejo:<owner>/<repo> | github:<owner>/<repo> | repo:<path> (validated by os-backlog config-write). (3) Card-as-pointer + issue-chain-as-spec: when a code effort needs both state tracking and a durable spec, the Planka card is a pointer (title + link) into the git issue chain holding the spec — never duplicate spec text into a card description. (4) Promotion rule: when a Planka-tracked effort accretes significant code/design decisions in card comments, that is the signal to promote — open a git issue (or chain) for the durable spec and turn the card into a pointer; the AI flags promotion to the user, never performs it silently. Operational detail lives in the cited sources (route SKILL.md, to-issues step 5, session_start.py note) and is not restated here; column-ownership rules are ADR-0029's.
Consequences
Easier: one recorded boundary the route skill, /to-issues, and the SessionStart note can all be audited against; changing the boundary now requires a superseding ADR rather than a quiet skill edit; the pilot plan's informal amendment has a durable home. Harder: two tracking surfaces per code project (board + issue tracker) instead of one, mitigated by the pointer pattern and back-links; promotion is a judgment call the AI can only flag, so under-flagging is a live risk (measured via the session-audit rubric).
Alternatives rejected
- Keep "Forgejo for everything" (original pilot plan) — rejected: process/coordination/household-style tasks have no repo home and card state (columns, WIP) is exactly what issue trackers do badly. 2) Planka for everything, specs in card descriptions — rejected: card descriptions are not durable, linkable, or commit-referenceable; specs need git-issue permanence. 3) Leave the rule in skill prose only, no ADR — rejected: prose rules drifting out of sync with enforcement is precisely what ADR-0029 fixed for column moves; the routing boundary deserves the same durability.