104 lines
6.3 KiB
Markdown
104 lines
6.3 KiB
Markdown
# Design: retire-planka-git-issues-only
|
|
|
|
## Context
|
|
|
|
os-backlog today (post-slice-8, 2026-07-13): Ruby lib + CLI over both a Planka board model
|
|
(board-ensure/resolve/card-*) and tracker inspection (`inspect`, `tracker.rb`,
|
|
`project_index.rb`), skills (capture/list/route), two Planka agents, a SessionStart
|
|
rules note (~447 tokens), an os-status grammar check, and a wakeup poller that already
|
|
reads git issues. ADR-0042 retires the Planka half. The issue-side plumbing (`tea` for
|
|
Forgejo, `gh` for GitHub, in-repo files for `repo:`) already exists and is what real work
|
|
has used. Constraint: the plugin is globally installed and ambient on every machine — the
|
|
rework must land whole (no half-migrated grammar), and source edits require
|
|
`bin/refresh-plugins` to reach sessions.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- One tracker per project holds both state and specs; `planka:` gone from the grammar.
|
|
- Preserve the durable process contracts: mid-session capture, pull-only listing,
|
|
priority + autonomy labels, human-only curation gate, cross-project filing.
|
|
- Leave zero dormant Planka infrastructure: cards migrated, server down, gem archived,
|
|
credentials revoked.
|
|
|
|
**Non-Goals:**
|
|
- A unified dashboard over git issues (explicitly deferred until it is a felt pain point).
|
|
- Reworking the wakeup poller (already issue-based; only its label reads are re-checked).
|
|
- Bulk re-onboarding of projects beyond rewriting their `tracker=` values.
|
|
- Any new home for client management (Invoice Ninja et al. own that; out of scope).
|
|
|
|
## Decisions
|
|
|
|
1. **State model = open/closed + labels, no status-label state machine.** Columns
|
|
Backlog/Next/Doing/Waiting/Review/Done collapse to: open issue (backlog), `next` label
|
|
(human-curated), assignee/linked-branch activity (doing — no label to maintain),
|
|
`waiting` label + a blocker comment, `review` label (semi work shipped), closed (done).
|
|
Rationale: every label the AI must maintain is a compliance cost the incentives review
|
|
flagged; keep only labels that carry information a human filters on. Alternative
|
|
rejected: full column-equivalent label set (`doing`, `done`) — duplicates what issue
|
|
state and assignment already express.
|
|
2. **Curation gate: `next` is human-only in skill/hook prose, not CLI-enforced.**
|
|
ADR-0029's CLI enforcement existed because Planka moves were CLI-mediated; issue labels
|
|
are set via tea/gh which os-backlog does not proxy. The rule lives in the SessionStart
|
|
note + skills, and the session-audit rubric (os-context category 8) measures compliance.
|
|
Alternative rejected: wrapping tea/gh in an enforcing CLI — rebuilds the proxy layer the
|
|
retirement is deleting.
|
|
3. **Non-repo/ops work: a private `ops` Forgejo repo, `tracker=forgejo:jared/ops`.**
|
|
The recurring Operations card becomes a recurring-convention issue there (comment +
|
|
reopen/leave-open, never close — mirrors the existing recurrence contract). Alternative
|
|
rejected: `repo:<path>` files — loses labels and the wakeup/query surface for the one
|
|
place recurring process work lives.
|
|
4. **Migration before demolition, human gate on client data.** Card migration runs while
|
|
Planka is still up; philly-search-engine-marketing (23 cards, real client backlog) is
|
|
migrated only after per-card human sign-off (destination: the client project's tracker
|
|
or the ops repo). cc-os non-Done cards → Forgejo `jared/cc-os` issues. Done cards are
|
|
not migrated (history stays in a final JSON snapshot archived to the ops repo before
|
|
decommission). Rollback: the snapshot + a Postgres dump taken before server teardown.
|
|
5. **Code removal is deletion, not deprecation.** `board_ensurer/board_resolver/
|
|
board_spec/cards` (Planka transport), both agents, and gem wiring are deleted with their
|
|
tests; `tracker.rb`/`inspector.rb`/`config.rb`/`project_index.rb`/`wakeup.rb` survive.
|
|
`Config#planka_board` and `Resolver` board logic go. Grammar validation rejects
|
|
`planka:` with a pointer to ADR-0042. Alternative rejected: feature-flagging Planka off
|
|
— dormant-code variant of the dormant-server trap.
|
|
6. **planka-api gem: archive the repo, keep no dependency.** The gem is user-authored and
|
|
unpublished; archival (read-only, README pointer to ADR-0042) preserves the
|
|
reverse-engineering knowledge without implying maintenance. The vault gotchas note
|
|
stays — it documents the API, not our use of it.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Untested non-repo workload loses its designated surface] → ops-repo issues are the
|
|
cheap test ADR-0042 calls for; revisit via a new ADR if it chafes in practice.
|
|
- [AI label discipline unenforced] → session-audit rubric already measures
|
|
tracker-routing compliance; the label contract is smaller than the column contract it
|
|
replaces (fewer states, fewer rules).
|
|
- [Client board migration loses nuance (comments, label history)] → per-card human gate;
|
|
full JSON snapshot archived first.
|
|
- [Stragglers: `.cc-os/config` files on other machines still saying `planka:`] →
|
|
config-write/os-status check rejects the value with a one-line re-route instruction;
|
|
fail-soft, never blocks a session.
|
|
- [Forgejo becomes a single point of failure for process state] → it already was for
|
|
specs and wakeup; repos sync to it from every machine and it is backed up with the VPS.
|
|
|
|
## Migration Plan
|
|
|
|
1. Land the plugin rework + spec deltas (tests green, `bin/refresh-plugins`).
|
|
2. Snapshot all boards to JSON; archive snapshot in the ops repo; Postgres dump on ovh-vps.
|
|
3. Create `jared/ops` repo + label set; move the recurring audit issue there.
|
|
4. Migrate cc-os non-Done cards → `jared/cc-os` issues (labels carried over).
|
|
5. Human-gated pass over philly-search-engine-marketing cards.
|
|
6. Rewrite `tracker=` in onboarded projects' `.cc-os/config`.
|
|
7. Revoke bot credentials; decommission Planka on ovh-vps; archive the gem repo.
|
|
8. Update docs: implementation-status leaf + index line, CLAUDE.md inventory line,
|
|
backlog-pilot vault note.
|
|
|
|
Rollback (any step before 7): Planka is still running; restore config values. After 7:
|
|
restore from Postgres dump — accepted as effectively one-way once step 7 runs.
|
|
|
|
## Open Questions
|
|
|
|
- Whether `philly-search-engine-marketing` cards land in a client repo tracker or the ops
|
|
repo (human decision during step 5).
|
|
- Which machine's cron (if any) hosts the wakeup poller — pre-existing open item, not
|
|
blocked by this change.
|