From e001bad2b5ccd4577480ad1ecee0087ac5a6152c Mon Sep 17 00:00:00 2001 From: Connor England Date: Mon, 13 Jul 2026 04:27:08 -0500 Subject: [PATCH] docs: record Linear sync projection gaps --- docs/LINEAR_SYNC_FINDINGS_2026-07-13.md | 63 +++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/LINEAR_SYNC_FINDINGS_2026-07-13.md diff --git a/docs/LINEAR_SYNC_FINDINGS_2026-07-13.md b/docs/LINEAR_SYNC_FINDINGS_2026-07-13.md new file mode 100644 index 0000000..00986f7 --- /dev/null +++ b/docs/LINEAR_SYNC_FINDINGS_2026-07-13.md @@ -0,0 +1,63 @@ +# Linear sync findings — 2026-07-13 + +Point-in-time findings from projecting the Pidgeon Health Conform product program: five PIs, 38 slices, and 117 estimated sessions. The source roadmap intentionally uses `meta.linear.horizon: near` so the day-to-day board carries actionable work rather than every optional future slice. + +## 1. `linear` does not honor the advertised input override + +The root help presents `-i | --in ` as a general roadmap-path override. `roadmap linear sync --dry -i ` still loads the repository's canonical `docs/roadmap/roadmap.yaml`, while placing `-i` before the command routes to `plan` because leading flags default to that command. + +Why it matters: an operator cannot safely preview an alternate projection policy or candidate roadmap without temporarily changing the canonical file. + +Recommended correction: + +- parse the input path once in the root CLI and pass it explicitly to every command; +- teach `linear.mjs` to derive the repo root, YAML path, cursor path, and write-back target from that resolved input; +- add CLI tests for `roadmap linear status|sync --in ` and for a leading global option. + +## 2. Projection horizon is global, but rollout intent is often per-PI + +`horizon: near` correctly suppresses new scheduled/optional issues. Already-mapped issues continue to update. The Conform program needed one deliberate full-program projection so its complete structure was visible in Linear, but switching to `horizon: all` also exposed six unrelated scheduled slices. + +Why it matters: teams need to publish one approved program without turning every speculative lane into board inventory or falsely promoting all of its work into the current cycle. + +Recommended correction: + +- support a scoped command such as `roadmap linear sync --pi conform-product-foundation,... --include-scheduled`; +- alternatively allow a PI-level projection override while retaining the repository default; +- keep cycle assignment status-driven: publishing a scheduled issue must not imply `next` or current-cycle commitment; +- print a preflight summary grouped by PI and status before any full-horizon push. + +## 3. One completed issue remains non-idempotent + +After repeated successful syncs, `roadmap linear sync --dry` continues to report `updateIssue PID-475`. Running the non-dry sync applies the update, but the next dry run proposes it again. All other push operations reconcile. + +Why it matters: a persistent false-positive weakens the "unchanged roadmap sends zero ops" contract and makes operators less likely to notice a real one-item delta. + +Recommended correction: + +- add an explain/debug mode that prints the exact field-level diff for each planned operation; +- normalize nullable/completed fields, labels, estimates, project milestones, assignee, and cycle values before comparison; +- capture PID-475's local and remote normalized payloads as a regression fixture; +- assert `sync -> dry sync` returns zero push operations for completed issues. + +## 4. The local cursor needs automatic hygiene + +The first live sync created `.roadmap-linear-state.json` in the repository root. The application repo did not ignore it, even though the deployment guidance treats the cursor as local state. + +Recommended correction: + +- have `roadmap linear setup` add the cursor path to `.gitignore` idempotently, or store it under the user's state directory; +- have `roadmap linear status` warn when the cursor is unignored; +- keep credentials and cursor state separate from committed roadmap configuration. + +## Acceptance target + +A high-velocity agentic cadence should support this loop without temporary canonical edits: + +1. preview a named PI's full projection; +2. see the exact create/update field diffs; +3. push only that scope; +4. preserve current-cycle commitments; +5. write stable IDs back to YAML; +6. rerun dry and receive zero operations; +7. keep the cursor local and ignored automatically.