releasekit/docs/roadmap/publication-reconciliation.md

# Roadmap: read-only publication reconciliation

Status: planned capability; storage, credential handling, and output decisions resolved.

## Purpose

Let maintainers revisit a failed or uncertain source-publication attempt through
one ReleaseKit operation. PromptKit currently copies the endpoint checks, exact
tag query, and result interpretation into its runbook. ReleaseKit should own
these mechanics and the handoff of original attempt evidence.

The target includes a public Go API and a CLI command with equivalent behavior.
This roadmap describes the end state and required work, without selecting a
release version or prescribing a staged implementation plan.

## Current baseline

The current checkout contains the v0.7.0 release notes and publication workflow.
The [publication guide](../consumers/publish.md) describes existing outcomes;
the [maintainer runbook](../release.md#resolve-failures) describes manual recovery.

- `PublicationResult` supplies the repository and module identity, semantic
  version, full tag, candidate commit, captured endpoint, tag object when known,
  phase, and publication state. Its endpoint can contain credentials.
- Internal `reconcilePush` makes a bounded authoritative observation after a
  failed push. It compares the annotated tag object and available peeled commit
  evidence, returning published, absent, conflicting, or unknown outcomes.
- `internal/git.Endpoint.QueryTag` verifies the captured endpoint's scoped URL
  resolution before querying the full tag and peeled ref. Inconsistent exact-ref
  records remain unresolved.
- The CLI masks HTTP(S) endpoint userinfo in diagnostics. The runbook still asks
  maintainers to copy the displayed endpoint and compare remote object IDs.
- There is no public operation or CLI command for later reconciliation, and no
  reusable CLI attempt record for preserving the exact transport endpoint.

These existing observations and classifications provide the implementation
foundation. The main additions are a reusable operation, original-evidence
handoff, and documented operator and automation interfaces.

## Targeted end state

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.

| Observation | Reconciliation outcome |
| --- | --- |
| Intended annotated tag object, with consistent available commit evidence | Published |
| Authoritative full tag absent | Not published |
| Different tag object, including one pointing at the same commit | Conflict |
| Observation failure, inconsistent records, or insufficient original evidence | Unknown |

The implementation preserves existing exact-object semantics, including current
handling of an unavailable peeled ref. A matching commit alone is insufficient.
Absence describes the current observation; it does not establish that the tag
never existed. A record identifies the intended attempt and is not proof that a
push happened or that the remote accepted it.

Reconciliation uses the original captured endpoint and full tag, including nested
module prefixes. It checks that URL rewriting still permits observation of that
endpoint. A changed remote configuration does not substitute a new destination.
Authentication remains locally supplied through the supported Git mechanisms.

The operation observes remote state without creating, pushing, moving, or
deleting tags, changing branches, validating a candidate, or delivering hosted
content. Current branch, worktree cleanliness, and current `HEAD` do not need to
match publication prerequisites. Repository context may still be used for Git
configuration and authentication. Corrective actions remain explicit.

Successful source publication retains its existing completion point. Later
reconciliation is an optional recovery operation, with no routine read-back,
polling, CI, consumer-installation, or delivery gate.

## Work needed

### 1. Extract a shared observation and classification path

**Rationale:** Immediate and later recovery should interpret the same evidence
consistently.

**Target:** A reusable internal operation observes the captured endpoint and
classifies its exact tag using the existing publication semantics.

**Work:** Separate remote observation and classification from the original push
error and publication orchestration. Reuse the scoped endpoint and exact-ref
query behavior. Keep immediate failed-push reconciliation bounded and preserve
its existing error context. Later reconciliation should honor caller cancellation
and return an unresolved outcome when observation cannot complete. It should not
invoke the current-remote equality guards that belong to an active publication.

### 2. Define public evidence and reconciliation results

**Rationale:** Consumers need supported types for recovery instead of rebuilding
internal Git behavior or parsing diagnostic strings.

**Target:** A root-facade operation, provisionally `ReconcilePublication`, accepts
original evidence and returns a useful observation with preserved error causes.

**Work:** Define the minimum evidence needed for each classification: captured
endpoint, full tag, intended tag object, and candidate commit as applicable.
Carry module/version information for operator context. Reuse existing publication
state meanings while distinguishing the original attempt from the new observation.
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.

Keep facade ownership and internal Git boundaries. Exact type names, field names,
and signatures belong in API design; no new public implementation package is
needed for this feature.

### 3. Provide a practical attempt-evidence handoff

**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
original evidence. Library consumers can retain equivalent typed data.

**Work:** Capture evidence when the endpoint and tag object are established,
before attempting the push. Preserve useful partial evidence if an earlier stage
fails, clearly identifying what is missing. Make record production and loading
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;
this feature does not require a transactional journal or power-loss guarantees.

### 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
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
observations, and cancellation. Replace the runbook's manual endpoint-copy
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.

### 5. Verify recovery behavior and integration

**Rationale:** Incorrect recovery can direct corrective action at the wrong
repository or mistake a different annotated tag for the intended release.

**Target:** Behavioral coverage establishes equivalent immediate/later
classification and useful recovery across process boundaries.

**Work:** Use temporary Git repositories and local remotes to cover exact matches,
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
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.

Run the normal offline suite and facade checks when code lands. Update GoDoc,
CLI documentation, the publication guide, and recovery instructions together.
Any release-policy clarification should describe later optional recovery without
adding checks to successful publication. This roadmap itself changes no code.

## Resolved decisions

### 1. Automatic storage with an optional path override

Retain records automatically in private repository-local Git metadata by default,
outside the tracked worktree, with a distinct record for each attempt. The
standard location should serve nearly all consumers without configuration.
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
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.

Automatic storage removes a routine setup decision and keeps default records
out of commits. Records accumulate locally, and recovery evidence can be lost
when storage fails or its location is removed. Document retention and manual
removal, including the sensitive nature of records at overridden locations.
Automatic cleanup is not required for the initial capability.

### 2. Preserve the exact endpoint in private records

Preserve the exact captured endpoint in the private record, with owner-only
access using platform-supported file permissions. Continue redacting endpoint
credentials in human and machine diagnostic output; expose only the record
location for the handoff. Prefer locally supplied Git credentials in adoption
guidance. Treat exports and copies of the record as potentially sensitive,
just like the existing API result's endpoint.

This supports existing publication configurations without reconstructing an
endpoint from its display. It also places potentially sensitive material on disk;
permissions and clear documentation reduce accidental exposure but do not promise
encrypted storage or protection from other processes running as the same user.

### 3. Human-readable and structured outcomes

Offer human-readable output by default and a structured mode with redacted
identity, reconciliation state, and cause information. Use success for confirmed
publication, a non-success classification for absence/conflict, and distinct
unknown and invocation-error classifications, following the existing CLI
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.