pcli/openspec/changes/archive/2026-02-19-kanban-sync-script/specs/kanban-sync-concurrency/spec.md

ADDED Requirements

Requirement: Exclusive sync execution

The sync script SHALL use flock advisory locking to ensure only one sync instance runs at a time per project-board pair. The lock file SHALL be located at /tmp/kanban-project-sync-<project>-<board>.lock.

Scenario: First sync acquires lock

• WHEN kanban-project-sync is invoked and no other sync is running for the same project-board
• THEN the script acquires the flock and executes the full sync

Scenario: Second sync finds lock held

• WHEN kanban-project-sync is invoked while another sync is running for the same project-board
• THEN the script SHALL NOT execute the sync, SHALL touch the pending flag file, and SHALL exit with code 0

Requirement: Coalescing pending queue

The sync script SHALL implement a depth-1 coalescing queue using a pending flag file at /tmp/kanban-project-sync-<project>-<board>.pending. Multiple pending requests SHALL coalesce into a single re-run.

Scenario: Pending flag set during sync

• WHEN a sync completes and the pending flag file exists
• THEN the script SHALL clear the pending flag and re-run the sync before releasing the lock

Scenario: No pending flag after sync

• WHEN a sync completes and no pending flag file exists
• THEN the script SHALL release the lock and exit

Scenario: Multiple pending requests coalesce

• WHEN three sync requests arrive while a sync is running
• THEN only one additional sync SHALL run after the current one completes (not three)

Requirement: Foreground and background modes

The sync script SHALL default to foreground execution (output to stdout/stderr). When --background is passed, the script SHALL detach and redirect output to a log file at /tmp/kanban-project-sync-<project>-<board>.log.

Scenario: Foreground execution

• WHEN kanban-project-sync is invoked without --background
• THEN sync output SHALL be written to stdout/stderr and the script SHALL block until complete

Scenario: Background execution

• WHEN kanban-project-sync is invoked with --background
• THEN the script SHALL detach from the terminal, redirect output to the log file, and return immediately

Requirement: Required arguments

The sync script SHALL require --project <name> and --board <name> arguments. The script SHALL NOT read project.yaml directly.

Scenario: Missing arguments

• WHEN kanban-project-sync is invoked without --project or --board
• THEN the script SHALL print usage information and exit with code 1

Requirement: Connectivity check

The sync script SHALL run pcli status before syncing. If the check fails, the script SHALL exit with code 2.

Scenario: Planka offline

• WHEN pcli status returns a non-zero exit code
• THEN the script SHALL print a message indicating Planka is unreachable and exit with code 2

Requirement: Idempotent sync phases

The sync script SHALL implement all 10 phases of the existing kanban-sync workflow: connectivity check, bootstrap infrastructure (find-or-create project, board, lists, label), gather OpenSpec state, determine target lists, gather Planka agent cards, create missing cards, move cards to correct lists, sync task checklists, handle archived changes, and report. Each phase SHALL be idempotent — running the script twice with no state changes SHALL produce no Planka API mutations on the second run.

Scenario: Clean re-run with no changes

• WHEN the sync script runs twice in succession with no OpenSpec or Planka state changes between runs
• THEN the second run SHALL make no create/update/move API calls and SHALL report zero changes