Phase: Auto-Population and Sync

phase-pal-e-docs-auto-population Phase

Project

Goal: Auto-discover items and keep boards in sync with source systems. Eliminate manual board maintenance.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 1 (Board Data Model) — COMPLETED

Scope

Sub-phase 5b-1: Plan/Phase Sync (internal)

Issue: forgejo_admin/pal-e-docs #165 (CLOSED) — PR #166 merged 2026-03-14. POST /boards/{slug}/sync endpoint + update_note hook. 16 tests, all 513 pass.
SDK: forgejo_admin/pal-e-docs-sdk #28 (CLOSED) — PR #29 merged 2026-03-14. sync_board(slug) method added, SDK v0.4.0 published.
MCP: forgejo_admin/pal-e-docs-mcp #37 (CLOSED) — PR #38 merged 2026-03-14. sync_board MCP tool added, MCP v0.3.0.
5b-1 COMPLETE — full stack: API → SDK v0.4.0 → MCP v0.3.0. Needs session restart to activate.

POST /boards/{slug}/sync — scans board for plan items, auto-creates BoardItems for child phases, maps note status → board column
Hook in update_note — when a phase note's status changes, find matching BoardItem by note_slug and move to the correct column
Status → Column mapping: not-started→backlog, in-progress→in_progress, completed→done, deferred→done
Duplicate prevention: skip phases already on the board (existing unique constraint on note_slug per board)
No new dependencies — purely internal to pal-e-docs DB

Sub-phase 5b-2: Forgejo Issue Sync (external)

Issue: forgejo_admin/pal-e-docs #170 (CLOSED) — PR #171 merged 2026-03-14. POST /boards/{slug}/sync-issues endpoint + Forgejo API client + config extension + k8s env vars. 9 tests, all passing.
Pre-deploy: forgejo-api-token key needed in pal-e-docs-secrets k8s secret.

POST /boards/{slug}/sync-issues — pull open issues from Forgejo repos via API
Match issues to existing BoardItems by forgejo_issue_url
New issues auto-create as backlog BoardItems
Closed issues auto-move to Done
Needs: Forgejo API token in env, project → repo mapping

Sub-phase 5b-3: Stale Detection

Issue: TBD

Flag items whose source was closed/completed outside the board
Flag items stuck in a column for too long
Add stale_at field to BoardItem (schema migration)
Periodic sweep (cron-like, similar to embedding worker pattern)

Deliverable

Adding a plan to a board auto-populates its child phases. update_note(status=...) auto-moves the corresponding board item. Forgejo issues sync into the board. Status changes propagate bidirectionally. All boards stay current with zero manual maintenance.