diff options
| author | Craig Jennings <c@cjennings.net> | 2026-05-24 19:50:28 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-05-24 19:50:28 -0500 |
| commit | c2fc84a11a0db1df981fcb978a675c516afc2252 (patch) | |
| tree | 67ab1a48180af9541ac1eac05c352bd3c2598cbb /docs | |
| parent | 617d3a13fa23b472879327366c6c557de9cb90f4 (diff) | |
| download | pearl-c2fc84a11a0db1df981fcb978a675c516afc2252.tar.gz pearl-c2fc84a11a0db1df981fcb978a675c516afc2252.zip | |
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ticket-save-model-spec.org | 16 |
1 files changed, 8 insertions, 8 deletions
diff --git a/docs/ticket-save-model-spec.org b/docs/ticket-save-model-spec.org index 8d7bc9a..40066ce 100644 --- a/docs/ticket-save-model-spec.org +++ b/docs/ticket-save-model-spec.org @@ -19,7 +19,7 @@ Editing a ticket today means picking the right per-field command: Three free-text fields, three commands, three things to remember. There's no single "I edited this ticket, save it" action, and no way to edit several fields (or several tickets) and push them all at once. In practice the save command would be the most-used command in the package, yet every field command currently has its own keybinding competing for finger memory. -* Current state +* Current State - *Provenance hashes* live in each issue's drawer and already encode "did this change since fetch": - =LINEAR-TITLE-SHA256= — hash of the displayed (bracket-stripped, title-cased, prefix-excluded) title. @@ -33,7 +33,7 @@ Three free-text fields, three commands, three things to remember. There's no sin - *Subtree iteration* exists: =pearl--issue-subtree-markers= walks every issue heading (used by the merge refresh). - *Discoverability* is the transient =pearl-menu=. -* Proposed design +* Proposed Design ** Architecture: a small save engine, not wrappers over interactive commands @@ -179,7 +179,7 @@ The "Issue at point" group loses the two field-sync entries (subsumed by save) a (The transient and the =pearl-prefix-map= are independent surfaces; the table above is the transient. The menu's existing key locks in transient tests, so this is the exact target.) -* Agreed decisions (this feature) +* Agreed Decisions (This Feature) 1. A layered save engine: pure dirty scanners → per-field async savers (marker + callback → structured outcome) → sequential queue runner → thin interactive wrappers. 2. Description dirty detection uses =LINEAR-DESC-ORG-SHA256= first, falling back to the markdown hash only for legacy subtrees; a push advances both hashes; the remote gate still uses the markdown hash. @@ -192,17 +192,17 @@ The "Issue at point" group loses the two field-sync entries (subsumed by save) a 9. Keybindings ship as an opt-in =pearl-prefix-map= (no global bind at load); README documents =C-; L= as a suggested binding. Verb layout =a= / =d= / =e= + =m=. 10. The transient "Issue at point" group is retargeted per the table above; the per-field sync commands stay callable but lose dedicated keys. -* Files touched +* Files Touched - =pearl.el=: =pearl--issue-dirty-fields= (local scanners); per-field async savers extracted from the current interactive commands; the sequential queue runner; =pearl-save-issue= / =pearl-save-all=; the interactive sync commands re-pointed as thin wrappers; =pearl-prefix-map= (define-prefix-command, populated, not bound); the retargeted =pearl-menu= group; description-push advancing both hashes. - =docs/=: this spec. - =README.org=: the save model + the suggested-binding snippet, with the existing title-bracket and markdown-lossiness warnings kept *near* the save docs (a unified save pushes title + description together, so the losses surface in one command). -* Test plan +* Test Plan New focused =tests/test-pearl-save.el= (rather than scattering into the per-field files): -*Dirty scan* +*Dirty Scan* - Clean rendered issue whose markdown is lossy under =org->md= → empty (via =LINEAR-DESC-ORG-SHA256=). - Legacy issue lacking the Org hash → falls back to the markdown hash. - Reports title-only, description-only, own-comment-only, multiple own comments, and mixed title+description+comment. @@ -233,7 +233,7 @@ New focused =tests/test-pearl-save.el= (rather than scattering into the per-fiel - Transient keeps the retargeted suffixes (locks the menu group). - README examples use the final command names and keep the lossiness warnings near the save docs. -* Review dispositions +* Review Dispositions *Round 1 (Codex, 2026-05-24).* Everything was accepted and woven into the body, *except* the two below, which were modified. @@ -244,7 +244,7 @@ Everything else — HP1 (Org-hash-first dirty detection), HP2 (structured outcom *Round 2 (Codex, 2026-05-24).* All accepted as written; no modifications. HP1 (two-phase comment ownership) corrected a genuine contradiction this author introduced in round 1 — the "no remote calls" save-all scan couldn't count read-only comment skips without the viewer id — and pinned the comment hash to =org->md= against =LINEAR-COMMENT-SHA256= (verified against =pearl--format-comment= and =pearl-edit-current-comment=). Folded in as the two-phase rule with a permitted pre-confirmation read-only viewer lookup. MP1 (multi-account not a prerequisite) and MP2 (stale =todo.org= wording) accepted; the stale task decisions block was trimmed to point at this spec rather than carry superseded pre-spec decisions. -* vNext / out of scope +* vNext / Out of Scope - Review-changes-before-save diff buffer (=git add -p= style) across the file before pushing. - A save-all dry-run command that reports dirty fields without prompting to push. |
