Roadmap board sync as a governed job — proposal¶
Status: proposal, 2026-10-08. It needs the HSSMeister governor's review
before anything is enabled.
Owner: spine maintainer with the HSSMeister governor
Implements: the execution section of the spine plan
plans/roadmap-threads-and-clickup-sync.md, and the roadmap item that derives
live sequencing from the board. That plan is tracked in the repository but is
deliberately not published on this site.
Why this is not a GitHub Actions workflow¶
The sync needs a ClickUp token with write access to the configured Spaces. Putting that in repository secrets would give every workflow run, and anyone who can edit a workflow file, the ability to rewrite the lab's roadmap board. The spine's convention, already applied to the weekly development report, is that this repository owns the deterministic engine and a governed runtime owns the credential, the schedule, the approval and the audit record.
So: the engine is scripts/roadmap_clickup.py, versioned and tested here. The
credential and the schedule belong to HSSMeister.
Interim, until the job exists¶
A maintainer runs the commands by hand from a spine session. The resulting commit or pull request is the audit trail, and the board edits are attributed to a dedicated member rather than to a person's own account.
CLICKUP_API_TOKEN=... python scripts/roadmap_clickup.py pull
git add roadmap/state && git commit -m "chore(roadmap): board reading <date>"
Create one ClickUp member named for the automation, give it access only to the
Spaces configured by roadmap.toml (HSSM roadmap and Venture today), and
use its token. Never a personal token, so revoking the automation never locks a
person out and never touches anything else.
The proposed capability¶
| Property | Value |
|---|---|
| Capability | roadmap.sync.v1 |
| Family | the engineering capability family this thread already proposes |
| Worker | scripts/roadmap_clickup.py, plain Python, no model |
| Caller | the glue layer, as a signed revocable identity |
| Credential | the ClickUp automation token, held by HSSMeister, never passed to the caller |
| Result visibility | internal |
| Approval mode | none for pull; owner approval for push and propose |
| Quota | one pull per day, one push per merge, both bounded by the API's 100 requests per minute on the Free plan |
| Failure owner | the spine maintainer |
Three steps, each with a different effect class:
pull— read only. It cannot write to ClickUp; the client refuses, so the step is safe to run unattended. Its result is a dated reading committed to the spine.push— writes intent to the board after a merge tomainchangedroadmap/. It never writes status, assignees, dates or comments, so it cannot overwrite anyone's judgement. Still owner-approved, because it is a write to a shared workspace.propose— read only against ClickUp; produces a pull-request body. Opening the pull request is an external effect and stays with a person, or with the approved pull-request capability once that exists.
What must be true before it is enabled¶
- The governor has reviewed this manifest and the capability family it joins.
- The ClickUp automation member exists and its token is held by HSSMeister, not by a person's environment.
- A policy test shows an ungranted caller cannot invoke the capability.
- One
pullhas run in shadow and its reading matches a hand-run reading. - The decision recording the work board is reflected in the roadmap, and the
Roadmap ID field and statuses exist in every configured Space, so
pushis not blocked.
What is deliberately not proposed¶
- No webhook receiver. Polling plus a push after merge is enough, and a receiver would be a new inbound network surface to govern.
- No write-back of status from Git to the board. That would break the one rule the whole design rests on.
- No automatic merge of a proposal. A person reviews every intent change.