Clarify publication recording and recovery selection

docs/roadmap/publication-reconciliation.md

@@ -1,6 +1,7 @@
 # Roadmap: read-only publication reconciliation
 
-Status: planned capability; storage, credential handling, and output decisions resolved.
+Status: planned capability; storage, selection, credential handling, and output
+decisions resolved.
 
 ## Purpose
 
@@ -43,6 +44,9 @@ After connectivity or authentication is restored, a maintainer can give
 ReleaseKit the original publication evidence and receive a fresh observation
 of that attempt's destination and full tag. Library consumers use typed evidence;
 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.
 
 | Observation | Reconciliation outcome |
 | --- | --- |
@@ -104,6 +108,9 @@ state meanings while distinguishing the original attempt from the new observatio
 Define behavior for incomplete evidence and unsupported record formats without
 inferring missing identity from today's remote, tag, or profile. A deleted or
 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.
 
 Keep facade ownership and internal Git boundaries. Exact type names, field names,
 and signatures belong in API design; no new public implementation package is
@@ -114,8 +121,9 @@ needed for this feature.
 **Rationale:** Redacted diagnostics are useful displays but cannot reliably carry
 the original transport URL into a later process.
 
-**Target:** The CLI can retain and read a small versioned record containing the
+**Target:** Shared publication automatically retains a small versioned record
-original evidence. Library consumers can retain equivalent typed data.
+for both Go API and CLI consumers. Library callers receive typed evidence,
+record location, and recording-failure information; the CLI presents that result.
 
 **Work:** Capture evidence when the endpoint and tag object are established,
 before attempting the push. Preserve useful partial evidence if an earlier stage
@@ -124,15 +132,16 @@ available through supported interfaces. Keep original identity separate from
 later observations and avoid replacing one attempt's evidence with another's.
 Implement automatic private storage with an optional path override and the
 sensitive-data handling recorded below. Use ordinary file handling proportionate
-to recovery;
+to recovery; this feature does not require a transactional journal or power-loss
-this feature does not require a transactional journal or power-loss guarantees.
+guarantees. Keep recording inside the shared publication path so library callers
+receive the same default and optional path override without consumer-owned hooks.
 
 ### 4. Expose recovery through the CLI and documentation
 
 **Rationale:** A single command should replace copied query and comparison steps.
 
-**Target:** A command provisionally named `reconcile` reads an attempt record and
+**Target:** A command provisionally named `reconcile` reads an explicitly selected
-reports the outcome, selected full tag, intended identity, and actionable cause
+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
@@ -142,6 +151,10 @@ procedure with this workflow and a concise link from consumer guidance. Explain
 how maintainers retain records and deliberately address absence or conflicts.
 Keep the distinction between source publication and hosted delivery explicit.
 Document recovery limits for older attempts that lack sufficient saved evidence.
+During publication, print a copyable recovery command when a saved record is
+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.
 
 ### 5. Verify recovery behavior and integration
 
@@ -156,7 +169,11 @@ absence, different objects at the same commit, root and nested tags, changed
 current remotes, rewriting that redirects the captured endpoint, inconsistent
 observations, unavailable remotes, and cancellation. Test record round trips,
 partial evidence, default and overridden storage paths, storage failures,
-private storage behavior, and redaction with synthetic credentials. Exercise
+private storage behavior, and redaction with synthetic credentials. Cover automatic
+recording through both API and CLI publication, direct typed-evidence recovery,
+and explicit selection among records for multiple modules and retries. Verify
+that recording failure remains separate from publication outcome and that the
+printed recovery command selects its original record. Exercise
 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.
@@ -178,8 +195,13 @@ Provide an optional storage-path override for consumers with particular needs.
 Apply the same record handling and privacy behavior at either location; exact
 configuration syntax belongs in interface design.
 
-Report the record path and allow explicit selection for reconciliation. Record
+Automatic recording belongs in the shared publication path for both Go API and
-evidence before the push once the necessary identity exists. Treat storage
+CLI callers. Publication results expose the saved record location and any
+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
 actual publication result and existing publication prerequisites. An override
 changes the location, not publication's response to a recording failure.
@@ -215,3 +237,15 @@ conventions where practical. Define exact numeric codes during CLI design.
 This makes shell recovery straightforward and keeps structured state authoritative
 for detailed consumers. A successful observation of absence still yields a
 non-success process status; document that distinction explicitly.
+
+### 4. Explicit attempt selection
+
+Reconciliation of a stored attempt requires an explicit record path. This keeps
+selection unambiguous across modules, retries, and changed repository state.
+When a record is available and recovery is relevant, publication prints a
+copyable command selecting that record. Automatic selection of the latest record
+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.