Vikunja PM system — design (tracking issue for vikunja-pm-system.md) #25
Labels
No labels
blocked:needs-decision
bug
chore
cron
design
in-progress
infra
milestone
module-o
needs-decompose
needs-research
ops-task
pm
quickfix
security/medium
triage-approved
vikunja
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
Mark/org_mode#25
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Design document
~/Projects/org_mode/docs/vikunja-pm-system.md— Vikunja + Hermes together replace OpenProject-style PM. Vikunja owns the PM artifact (plan spine, projects, milestones, dependencies, tasks). Hermes owns mechanical PM triggers, cross-substrate wiring, execution feedback. No monolith.Substrate split (settled)
Join keys via mention, no shared database. Vikunja does not talk to Forgejo directly — the kanban is the bridge.
Build milestones
Each is a separate Forgejo issue, linked below:
Verification gate
workers/verify-vikunja-pm.shsmoke test runs against a fresh Vikunja project with 3 mixed-due-date tasks + a milestone. All 4 PM crons run. Confirms: drift cron emits overdue+today observations, milestone rollup shows correct %, stale janitor clean, weekly digest synthesizes. No milestone ships until smoke test passes against real Vikunja, not mocked.Open design questions (defaults in parens)
Refs
docs/kanban-design.md§1 — Vikunja-as-truth principledocs/kanban-roadmap.mdModules A/B/D/E/N/O/Psrc/server/vikunja_api.py— Vikunja REST client (live)workers/vikunja-webhook-to-kanban.sh— existing inbound ingress (live)workers/vikunja-project-init.sh— existing idempotent project init (live)🔧 CORRECTION (2026-08-21) — static workers are WRONG
Major error caught by the user: this design originally mapped the PM observation
layer onto static cron scripts (
vikunja-pm-deadline-drift.py,-milestone-rollup.py,-stale-janitor.py,-weekly-review.py,verify-vikunja-pm.sh). That breaks the substrate principle:Those scripts were (a) none of them ever built — all absent from disk, and
(b) the wrong shape even if they were — they are static nonsense, not proper
auto-dispatched kanban agents.
Corrected design (
docs/vikunja-pm-system.md§3, §9, §10, §12):(wired into Module B
admin-janitorper §5.1), taggedlane: pm-observer.observation/review card or room post. No static script.
to auto-assign to the PM observer agent — not a script schedule.
not a bash smoke test.
M-PM-3 = "PM observer agent + lane"; M-PM-5 = "Milestone-close review".
Live-state check (2026-08-21):
vikunja-kanban-synccron IS live + healthy (every 1m, no_agent,last_status OK, 43 inbound_done_mirrored on last pass). The outbound bridge
in
~/Projects/hermes-scripts/scripts/vikunja-kanban-sync.pyis real andworking. The
worker vikunja-sync-worker.{py,sh}are deprecation stubs —NOT the live path.
working: subtasks via
related_tasks(task #59 → [60,61,62,63]).done=True, zero open.🔧 CORRECTION #2 (2026-08-21) — agent profile, not a lane; sync untouched
Second round of the correction:
M-PM-2 (sync) is DROPPED from scope. The Vikunja↔kanban sync bridge
(
vikunja-kanban-synccron, every 1m) is LIVE and healthy — verified 43inbound_done_mirrored, errors 0, 48 mapping rows. It will NOT be reworked.
#27 is now an out-of-scope info issue.
PM observation is a new dedicated profile
pm-observer— NOT a lane onadmin-janitor(no such profile exists) and NOT a lane onjanitor(janitoris coupled to the GSD pipeline). New directory with SOUL.md/config/.env/
skills/memory; self-registered by file existence (§13).
Cards are for the dispatcher → agent, NOT for a human to read. No
"create a card a human looks at" script. Triggers assign cards to the
pm-observer profile (qa-post-deploy-trigger / verifier-trigger precedent);
the agent delivers its report to the project room.
Milestones renumbered: M-PM-1 baseline · M-PM-2 pm-observer profile ·
M-PM-3 spec→swarm (Module O) · M-PM-4 milestone-close review.
🧹 PURGE (2026-08-21) — phantom PM machinery removed from the plan
Following ground-truth review of the implemented substrate, the entire
pm-observer/ cadence / rollup / review / build-milestone layer has beenpurged as incompatible invention. Nothing in it matched how the system
actually runs.
What the substrate actually is (confirmed on disk):
tasker-workeron thetaskerboard is the PM driver(
~/.hermes/profiles/tasker-worker/SOUL.md): it drains Vikunja-backed cards,classifies them (physical/human-op → do support then block; code → route via
Forgejo issue; non-code → do inline), and writes back to Vikunja on
complete/block. It is the writer, not a sync layer.
vikunja-webhook-to-kanban.shis the inbound ingress, event-driven via thedaemon ("DO NOT CRON IT"). The 1m poll cron is retired.
vikunja-kanban-synccron is the outbound catch-up, not the writer.Purged from
docs/vikunja-pm-system.md: thepm-observerprofile, thedrift/rollup/stale/weekly triggers, the cadence/review section, the M-PM build
milestones, and the phantom verification gate. Rewritten to describe the
implemented
tasker-workerdriver + real ing,estion path + PM principles.Closed as superseded: #26 (baseline — already implemented), #28 (pm-observer
profile — phantom), #30 (milestone-close review — phantom). #29 retitled to
stand alone as a roadmap (Module O) item, decoupled from the killed M-PM scheme.
#27 remains an out-of-scope note (sync bridge untouched).
The user confirmed: the current substrate is more correct in implementation and
goals; it already processes Vikunja tasks and, where not directly actionable,
does what it can to support human ops.
Closing — design/tracking issue for vikunja-pm-system.md. Doc lives in ~/Projects/org_mode/docs/. Reopen if work is wanted.