releasekit/docs/roadmap/publication-reconciliation.md

Roadmap: read-only publication reconciliation

Status: planned capability; recommendations under Open Decisions await resolution.

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 describes existing outcomes; the maintainer runbook 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. Resolve persistence defaults and sensitive-data handling below before defining the storage contract. 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, 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.

Open Decisions

1. How should the CLI persist attempt records?

Recommendation: Retain records automatically in private repository-local Git metadata, outside the tracked worktree, with a distinct record for each attempt. 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.

This removes a routine setup decision and keeps records out of commits. The tradeoffs are local metadata accumulation and possible loss of recovery evidence when storage fails or the checkout is removed. Document retention and manual removal; automatic cleanup is not required for the initial capability.

Alternative: Require an explicit output path to enable recording. This makes persistence deliberate and works naturally with caller-managed storage. It adds launcher configuration and offers no durable handoff when a maintainer forgets the option. A requested write could fail before the push if the caller requires that handoff, but such behavior would need an explicit interface contract.

2. How should a record represent credential-bearing endpoints?

Recommendation: 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.

Alternative: Store a credential-free endpoint and obtain authentication only through local mechanisms. This reduces secrets in records, but stripping userinfo can affect transport identity and rewriting. Adopting it requires a deliberate endpoint-identity contract and migration guidance for credential-bearing URLs. It cannot simply use the existing redacted display as a transport URL.

3. What should automation receive?

Recommendation: 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. The tradeoff is that a successful observation of absence still yields a non-success process status; document that distinction explicitly.

Alternative: Return success for every completed observation, including absence and conflict, and require automation to read the structured state. This cleanly separates query execution from publication outcome, but a simple exit-code check could be mistaken for confirmation that publication succeeded.