From 58c20fa863128bec40d7d63c457d582c2d1df154 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 2 Nov 2026 17:43:27 +0000 Subject: [PATCH] Add recovery ergonomics to reconciliation roadmap --- docs/roadmap/publication-reconciliation.md | 54 ++++++++++++++++++++-- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/docs/roadmap/publication-reconciliation.md b/docs/roadmap/publication-reconciliation.md index c39cbe5..3773eda 100644 --- a/docs/roadmap/publication-reconciliation.md +++ b/docs/roadmap/publication-reconciliation.md @@ -47,6 +47,9 @@ CLI consumers use a record produced by ReleaseKit without parsing diagnostics. Both Go API and CLI publication automatically retain attempt records through the shared publication path. Recovery selects a stored record explicitly; Go callers may also supply sufficient retained typed evidence directly. +Maintainers can discover saved attempts through a local, read-only listing when +the original publication output is unavailable. Discovery leaves record selection +explicit. | Observation | Reconciliation outcome | | --- | --- | @@ -111,6 +114,10 @@ moved local tag should not invalidate otherwise sufficient retained evidence. Expose the saved record location and any recording failure separately from the publication outcome. Accept retained typed evidence directly for reconciliation so observation does not depend on filesystem persistence. +Return a single facade-owned evidence value from publication that reconciliation +accepts directly. Provide a supported record-loading helper returning that same +type so Go consumers can recover without copying fields or implementing JSON +parsing. Keep facade ownership and internal Git boundaries. Exact type names, field names, and signatures belong in API design; no new public implementation package is @@ -141,8 +148,9 @@ receive the same default and optional path override without consumer-owned hooks **Rationale:** A single command should replace copied query and comparison steps. **Target:** A command provisionally named `reconcile` reads an explicitly selected -attempt record and reports the outcome, selected full tag, intended identity, and actionable cause -context. Automation has a documented structured result and exit behavior. +attempt record and reports the outcome, selected full tag, intended identity, +and actionable cause context. Automation has a documented structured result and +exit behavior. **Work:** Map the command to the facade, retaining credential-safe displays and errors. Document valid invocation, missing or unreadable records, unknown @@ -156,6 +164,21 @@ available and recovery is relevant. Include the explicit record path, with appropriate argument quoting, and preserve credential-safe output. Select the record supplied by the caller rather than inferring the latest attempt. +Add a local, read-only attempt listing for the default or explicitly selected +storage location. Show each record's path, module, full tag, candidate commit, +and recording time when available, with credentials redacted. Record the time +as discovery metadata; it does not establish whether a push occurred. Listing +reads saved records without querying remotes or choosing an attempt for recovery. +Include discovery in the recovery guide for interrupted processes and lost output. + +Make unresolved diagnostics identify missing evidence, unreadable records, +endpoint rewriting, and failed remote observation distinctly. Identify the +specific missing information or configuration issue when known and explain the +next useful operator action. For conflicts, show expected and observed tag-object +IDs. Preserve cause information without guessing whether a transport failure is +an authentication or connectivity problem. Apply these diagnostics to human and +structured output while leaving corrective actions explicit. + ### 5. Verify recovery behavior and integration **Rationale:** Incorrect recovery can direct corrective action at the wrong @@ -178,6 +201,12 @@ recording before a failed or interrupted push and a later invocation after local branch or tag state changes. Verify the diagnostic operation performs no publication or cleanup actions and runs no candidate tests. Reuse existing tests for unchanged Git behavior rather than duplicating them. +Verify that publication and record loading yield evidence directly usable by the +Go reconciliation API. Cover discovery across modules and retries, default and +overridden storage locations, partial records, and credential redaction. Verify +that listing performs no remote observation or automatic attempt selection. +Cover the diagnostic distinctions and expected/observed conflict identities +without requiring incidental error wording. Run the normal offline suite and facade checks when code lands. Update GoDoc, CLI documentation, the publication guide, and recovery instructions together. @@ -201,8 +230,9 @@ recording failure separately from the publication outcome. The library returns this information and the CLI presents it. Report the record path and require explicit selection for stored-record -reconciliation. Record evidence before the push once the necessary identity exists. Treat storage -failure as a clearly reported loss of the saved handoff, while preserving the +reconciliation. Record evidence before the push once the necessary identity +exists. Treat storage failure as a clearly reported loss of the saved handoff, +while preserving the actual publication result and existing publication prerequisites. An override changes the location, not publication's response to a recording failure. @@ -249,3 +279,19 @@ is outside this workflow. Go callers may instead reconcile sufficient retained typed evidence directly. Explicit stored-record selection does not make filesystem storage a prerequisite for the observation API. + +### 5. Recovery ergonomics + +Provide local attempt discovery to recover the record path after an interrupted +process or lost publication output. Listing exposes useful, credential-safe +identity and recording metadata while preserving explicit selection. + +Publication returns one reusable typed evidence value. Reconciliation accepts +that value directly, and the supported record loader returns the same type. +These interfaces keep evidence transfer and serialization mechanics in ReleaseKit. + +Diagnostics distinguish missing evidence, unreadable records, endpoint rewriting, +and failed remote observation, and identify useful next actions when known. +Conflict output includes expected and observed tag-object IDs. This makes +recovery actionable while preserving the existing outcome classifications and +explicit corrective-action workflow.