Shared sync fields¶

The transferable surface between git (source of truth) and any board (Notion, GitHub Projects, Jira). Detail stays in the plan / ADR / *.effort.json; the board only gets these rollups and identity keys.

Produced by scripts/sync-payload.mjs → computeFields(), emitted by scripts/format-sync.mjs.

Field set¶

Canonical key	Purpose	Typical board surface
`plan_id`	Stable slug — lookup key	Plan ID property / label
`progress_headline`	👀 one-line effort rollup	Text / “Status summary”
`current_plan_phase`	Active + next phase detail	Detail-only text (not card face)
`status`	Coarse status	Status / single-select
`pct_complete`	Percent complete	Number (optional on GitHub)
`effort_done` / `effort_total` / `effort_remaining`	Fibonacci rollups	Numbers / Estimate
`steps_done` / `steps_total`	Step counts	Numbers (optional)
`phases_done` / `phases_total`	Phase counts	Numbers (optional)
`plan_synced_at`	Exact sync date	Date (+ formula “Last sync” if available)

Plus links built from git origin (preferred) or hoen.yaml + plan path:

Derived	Purpose
Plan doc URL	Browseable URL on GitHub / Azure DevOps / Bitbucket — never a local path
Work type / Component type	Epic · Story · ADR · … / repo filter

When automated board write fails, emit a paste-ready block:

node library/skills/work-tracking/scripts/format-sync.mjs \
  --input path/to/plan.effort.json --paste-md --plan-doc path/to/plan.md

Progress headline format¶

👀 {pct}% complete - {done} / {total} effort points · {stepsDone} / {stepsTotal} steps · {remaining} remaining

Plan markdown may use a two-line 👀 block (summarize-effort.mjs --markdown-top); the board uses the single-line form above.

ADRs without effort JSON: set progress_headline from the ADR Status table (e.g. Accepted: … · Open: …); leave numeric effort fields empty.

Property name maps¶

node library/skills/work-tracking/scripts/format-sync.mjs \
  --input path/to/plan.effort.json --map notion --pretty

node library/skills/work-tracking/scripts/format-sync.mjs \
  --input path/to/plan.effort.json --map github --pretty

Canonical key	Notion (`--map notion`)	GitHub (`--map github`)
`progress_headline`	Progress headline	Status summary
`current_plan_phase`	Current plan phase	Phase detail
`status`	Status	Status
`effort_total`	Effort total	Estimate
(others)	Same human names as key titles	Optional / fold into summary

Never hand-sum Fibonacci points for the board.

Field bootstrap¶

On first link to a board:

Prefer creating these fields as first-class board properties (searchable, viewable).
Persist resolved field IDs under hoen.yaml → work_tracking.board.fields when available.
If create is refused or impossible: stamp values into description/body / available fields, note deferred fields, retry create on the next sync.