Clear GitHub sync mappings

[SorraTheOrc]

Intake Draft: Clear GitHub sync mappings (WL-0MMKOPME017N21S0)

Headline

Clear persisted GitHub mapping fields and local push-state with backups to prevent cross-machine sync conflicts.

Problem statement

Back up .worklog, clear githubIssueId/githubIssueNumber/githubIssueUpdatedAt from the DB, clear comment githubCommentId/githubCommentUpdatedAt, remove local push-state files and logs, and remove GitHub fields from .worklog/worklog-data.jsonl. Backups created under .worklog.bak and .worklog/*.bak.

Users

• Repository maintainers and operators who run wl sync and wl github push. Example user story: "As an operator, I want to remove persistent GitHub mapping fields and local push-state so that stale mappings don't persist across machines or cause sync conflicts when syncing with GitHub."

Success criteria

• A documented backup of .worklog is created under .worklog.bak before any clearing occurs.
• All GitHub mapping fields (githubIssueId, githubIssueNumber, githubIssueUpdatedAt, githubCommentId, githubCommentUpdatedAt) are cleared from the runtime DB and from exported .worklog/worklog-data.jsonl without data loss (original values preserved in the backup).
• Local push-state files and associated logs are removed or migrated to the approved per-machine storage solution, and the system remains functional for wl github push on machines with and without prior local state.
• Relevant tests updated and passing locally: unit tests referencing githubIssueId updated where necessary and the full project test suite run locally with no regressions.
• All related documentation and code comments updated to reflect the new behaviour, including README and developer notes where appropriate.

Constraints

• Must create backups before any destructive changes. Backups should be accessible under .worklog.bak and .worklog/*.bak.
• Maintain compatibility with the ephemeral JSONL transport pattern (Phase 2 design). Changes to .worklog/worklog-data.jsonl must follow the project's JSONL semantics.
• Preserve machine-local push-state semantics where required; do not introduce cross-machine data loss for legitimate push-state that is per-machine.

Risks & assumptions

• Risk: Clearing fields may break tests or external integrations that expect persisted GitHub mappings. Mitigation: run and update tests, and preserve original values in backups.
• Risk: Removing push-state files could cause unexpected duplicate pushes or missed pushes on machines that relied on local state. Mitigation: prefer migration to per-machine store (WL-0MLWTYH2H034D79E) or clearly document the behavioural change.
• Risk: JSONL export/import incompatibility with other tools that parse GitHub fields. Mitigation: follow Phase 2 ephemeral JSONL semantics and include migration notes in the backup and release notes.
• Assumption: Backups stored under .worklog.bak will be accessible to maintainers and retained long enough for rollback if needed.
• Scope-scope mitigation: Record any additional features or refactors discovered while implementing this task as separate work items linked to this item; do not expand scope of this task during implementation.

Existing state

• The repo currently persists GitHub mapping fields in both the DB and JSONL exports. src/github-sync.ts, src/persistent-store.ts, src/jsonl.ts, and src/github-push-state.ts are primary touchpoints. Several tests and work items rely on seeded mapping fields.

Desired change

• Implement a safe clear-and-backup operation that: (1) creates a timestamped backup of .worklog and any JSONL exports, (2) clears mapping fields in the DB, (3) removes GitHub fields from .worklog/worklog-data.jsonl, and (4) removes or migrates local push-state files/logs to the approved per-machine store.

Related work (automated report)

This conservative, curated list contains work items and repository files that are clearly relevant to "Clear GitHub sync mappings (WL-0MMKOPME017N21S0)". Each entry includes a pointer and a 1–2 sentence note explaining the relevance.

Work items

• WL-0MLWTYH2H034D79E — Implement local-only per-machine storage for the last successful wl github push timestamp
  Link: wl show WL-0MLWTYH2H034D79E
  Relevance: Directly implements the per-machine push-state file feature the current item wants to remove/replace; contains design/acceptance criteria for writing/reading the .worklog/.local/github-push-state.json file.

• WL-0MNFZ7J0T000EQDL — Stabilize CLI GitHub push tests against timeout flakiness
  Link: wl show WL-0MNFZ7J0T000EQDL
  Relevance: Test fixtures and push-path adjustments in this item seed and verify githubIssueId/githubIssueNumber/githubIssueUpdatedAt behavior — clearing those DB fields will affect these tests and fixtures.

• WL-0MN81ZNXR0025TPZ — Add tests for throttler and github-sync
  Link: wl show WL-0MN81ZNXR0025TPZ
  Relevance: Covers github-sync behaviour and scheduling; clearing GitHub mappings or removing push-state files alters runtime assumptions in sync code exercised by these tests.

• WL-0MN834ICI00339E7 — Deduplicate double-scheduling in github-sync
  Link: wl show WL-0MN834ICI00339E7
  Relevance: Changes to github-sync scheduling and state-management are directly relevant because WL-0MMKOPME017N21S0 intends to remove persisted GitHub mapping fields that github-sync currently reads/writes.

• WL-0MN598NES1TE8N8K — Phase 2: Implement ephemeral JSONL pattern
  Link: wl show WL-0MN598NES1TE8N8K
  Relevance: Describes the JSONL-as-transport design and migration guidance; removing GitHub fields from .worklog/worklog-data.jsonl must align with the ephemeral-JSONL semantics in this work item.

• WL-0MKRRZ2DN1R0JP9B — Sync blocked on Git Pull (sync/git/JSONL conflict handling)
  Link: wl show WL-0MKRRZ2DN1R0JP9B
  Relevance: Documents real-world conflicts and merge handling for .worklog/worklog-data.jsonl; clearing GitHub fields and cleaning push-state files will affect the sync/merge scenarios described here.

Repository files and tests (high-confidence)

• src/github-sync.ts — Primary codepath mapping work items to GitHub issues; reads/writes the github* fields.
• src/github-push-state.ts — Manages the local push-state file under .worklog/.local/.
• src/jsonl.ts — Handles export/import of .worklog/worklog-data.jsonl and parses fields such as githubIssueId.
• src/persistent-store.ts — Database schema and persistence code that declares the githubIssueId column.
• tests/cli/github-push-batching.test.ts — Test fixture that seeds githubIssueId values and verifies push batching.

Appendix: Clarifying questions & answers

• Q: "Is this operation intended to be reversible?" — Answer (agent inference): "Yes; the draft mandates creating backups under .worklog.bak before clearing any fields." Source: existing work item description. Final: yes.
• Q: "Should local push-state files be deleted or migrated to a per-machine store?" — Answer (user/stakeholder not provided): "Prefer migration to the approved per-machine store if design exists (see WL-0MLWTYH2H034D79E), otherwise remove with documented rationale." Source: related work; Final: TBD pending clarification.
• Q: "Are database schema migrations allowed or preferred? (yes/no)" — Answer (agent inference): "Allowed if necessary, but preference is to clear fields rather than drop columns to preserve schema compatibility." Source: repository patterns and conservative approach. Final: TBD pending clarification.

---

Draft created by automated intake assistant for WL-0MMKOPME017N21S0.