base-layer/releasekit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Resolve publication reconciliation roadmap decisions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-02 17:17:23 +00:00
parent e0bf5ca57a
commit bff4ed8a8b
1 changed files with 38 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/roadmap/publication-reconciliation.md
View File

@@ -1,6 +1,6 @@
# Roadmap: read-only publication reconciliation # Roadmap: read-only publication reconciliation
Status: planned capability; recommendations under Open Decisions await resolution. Status: planned capability; storage, credential handling, and output decisions resolved.
## Purpose ## Purpose
@@ -122,8 +122,9 @@ before attempting the push. Preserve useful partial evidence if an earlier stage
fails, clearly identifying what is missing. Make record production and loading fails, clearly identifying what is missing. Make record production and loading
available through supported interfaces. Keep original identity separate from available through supported interfaces. Keep original identity separate from
later observations and avoid replacing one attempt's evidence with another's. later observations and avoid replacing one attempt's evidence with another's.
Resolve persistence defaults and sensitive-data handling below before defining Implement automatic private storage with an optional path override and the
the storage contract. Use ordinary file handling proportionate to recovery; sensitive-data handling recorded below. Use ordinary file handling proportionate
to recovery;
this feature does not require a transactional journal or power-loss guarantees. this feature does not require a transactional journal or power-loss guarantees.
### 4. Expose recovery through the CLI and documentation ### 4. Expose recovery through the CLI and documentation
@@ -154,8 +155,9 @@ classification and useful recovery across process boundaries.
absence, different objects at the same commit, root and nested tags, changed absence, different objects at the same commit, root and nested tags, changed
current remotes, rewriting that redirects the captured endpoint, inconsistent current remotes, rewriting that redirects the captured endpoint, inconsistent
observations, unavailable remotes, and cancellation. Test record round trips, observations, unavailable remotes, and cancellation. Test record round trips,
partial evidence, private storage behavior, and redaction with synthetic partial evidence, default and overridden storage paths, storage failures,
credentials. Exercise recording before a failed or interrupted push and a later 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 invocation after local branch or tag state changes. Verify the diagnostic
operation performs no publication or cleanup actions and runs no candidate tests. operation performs no publication or cleanup actions and runs no candidate tests.
Reuse existing tests for unchanged Git behavior rather than duplicating them. Reuse existing tests for unchanged Git behavior rather than duplicating them.
@@ -165,61 +167,51 @@ CLI documentation, the publication guide, and recovery instructions together.
Any release-policy clarification should describe later optional recovery without Any release-policy clarification should describe later optional recovery without
adding checks to successful publication. This roadmap itself changes no code. adding checks to successful publication. This roadmap itself changes no code.
## Open Decisions ## Resolved decisions
### 1. How should the CLI persist attempt records? ### 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.
**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 Report the record path and allow explicit selection for reconciliation. Record
evidence before the push once the necessary identity exists. Treat storage evidence before the push once the necessary identity exists. Treat storage
failure as a clearly reported loss of the saved handoff, while preserving the failure as a clearly reported loss of the saved handoff, while preserving the
actual publication result and existing publication prerequisites. actual publication result and existing publication prerequisites. An override
changes the location, not publication's response to a recording failure.
This removes a routine setup decision and keeps records out of commits. The Automatic storage removes a routine setup decision and keeps default records
tradeoffs are local metadata accumulation and possible loss of recovery evidence out of commits. Records accumulate locally, and recovery evidence can be lost
when storage fails or the checkout is removed. Document retention and manual when storage fails or its location is removed. Document retention and manual
removal; automatic cleanup is not required for the initial capability. removal, including the sensitive nature of records at overridden locations.
Automatic cleanup is not required for the initial capability.
**Alternative:** Require an explicit output path to enable recording. This makes ### 2. Preserve the exact endpoint in private records
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? Preserve the exact captured endpoint in the private record, with owner-only
access using platform-supported file permissions. Continue redacting endpoint
**Recommendation:** Preserve the exact captured endpoint in the private record, credentials in human and machine diagnostic output; expose only the record
with owner-only access using platform-supported file permissions. Continue location for the handoff. Prefer locally supplied Git credentials in adoption
redacting endpoint credentials in human and machine diagnostic output; expose guidance. Treat exports and copies of the record as potentially sensitive,
only the record location for the handoff. Prefer locally supplied Git credentials just like the existing API result's endpoint.
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 This supports existing publication configurations without reconstructing an
endpoint from its display. It also places potentially sensitive material on disk; endpoint from its display. It also places potentially sensitive material on disk;
permissions and clear documentation reduce accidental exposure but do not promise permissions and clear documentation reduce accidental exposure but do not promise
encrypted storage or protection from other processes running as the same user. encrypted storage or protection from other processes running as the same user.
**Alternative:** Store a credential-free endpoint and obtain authentication only ### 3. Human-readable and structured outcomes
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? Offer human-readable output by default and a structured mode with redacted
identity, reconciliation state, and cause information. Use success for confirmed
**Recommendation:** Offer human-readable output by default and a structured mode publication, a non-success classification for absence/conflict, and distinct
with redacted identity, reconciliation state, and cause information. Use success unknown and invocation-error classifications, following the existing CLI
for confirmed publication, a non-success classification for absence/conflict, conventions where practical. Define exact numeric codes during CLI design.
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 This makes shell recovery straightforward and keeps structured state authoritative
for detailed consumers. The tradeoff is that a successful observation of absence for detailed consumers. A successful observation of absence still yields a
still yields a non-success process status; document that distinction explicitly. 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.