diff --git a/docs/roadmap/publication-reconciliation.md b/docs/roadmap/publication-reconciliation.md index ca07aab..dcb28fc 100644 --- a/docs/roadmap/publication-reconciliation.md +++ b/docs/roadmap/publication-reconciliation.md @@ -1,6 +1,6 @@ # 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 @@ -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 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; +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 @@ -154,8 +155,9 @@ classification and useful recovery across process boundaries. 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 +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. @@ -165,61 +167,51 @@ 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 +## 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 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. +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 -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. +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. -**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. Preserve the exact endpoint in private records -### 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. +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. Human-readable and structured outcomes -### 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. +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. +for detailed consumers. A successful observation of absence still yields a +non-success process status; document that distinction explicitly.