Define remote forge to SSOT refs sync, retention, restore, and readback mechanism

[roccho-dev]

Purpose

Define the effectful mechanism for syncing remote forge provider surfaces into SSOT refs without making the remote forge a meaning authority.

This issue is split out from roccho-dev/adrs#191. ADRS #191 should consume this mechanism as a blocking readiness dependency, not implement it.

Scope

Build or specify the mechanism for:

• remote forge issue / PR / branch / release / package observation;
• SSOT ref update with exact lease;
• provider observation refs;
• conflict refs for stale or unsafe provider updates;
• receipt refs for every allowed/rejected update;
• retention and restore proof;
• remote readback proof;
• rollback path;
• writer policy that prevents provider events from writing accepted meaning refs.

Non-goals

• Do not decide ADRS retirement.
• Do not create accepted ADRS state.
• Do not make GitHub, GitHub Issues, GitHub PRs, GitHub Projects, CI green, releases, packages, or workflow artifacts accepted meaning authority.
• Do not collapse roccho-dev/adrs#191 into a transport implementation issue.

Required outputs

The mechanism must provide, for every accepted or retained input ref:

• source SSOT ref;
• oid / digest;
• writer identity;
• promotion or write receipt;
• retention proof;
• restore proof;
• remote readback proof;
• rollback path;
• conflict handling rule;
• proof that provider events cannot write refs/brain/accepted/*.

Reference surface roles

surface role	example	long-lived dependency	temporary use	authority
ssot	self-hosted Git refs	yes	yes	yes
checked-mirror	GitHub main as mirror of SSOT selected ref	yes, if checked	yes	no
preview-branch	GitHub work/dev branch	no	yes	no
review-surface	GitHub PR	no	yes	no
coordination-surface	GitHub Issue / Project	no	yes	no
release-snapshot	GitHub Release	yes	yes	no
package-output	Nix output / binary cache / package artifact	yes	yes	no
public-projection	console / Pages / dashboard	read-only only	yes	no
backup	remote forge mirror / retained refs	yes, for recovery	yes	no

Suggested ref layout

ref	role
refs/provider/<forge>/issues/<repo>/<number>	observed issue state
refs/provider/<forge>/pull_request/<repo>/<number>	observed PR state
refs/provider/<forge>/branches/<repo>/<branch>	observed provider branch state
refs/provider/<forge>/releases/<repo>/<tag>	observed release snapshot state
refs/provider/<forge>/packages/<repo>/<package>	observed package output state
refs/conflicts/<forge>/...	stale / unsafe / authority-claiming provider event
refs/receipts/<forge>-to-ssot/<delivery>	audit receipt
refs/items/<id>	canonical work item, updated only through accepted lease policy
refs/brain/accepted/*	never written directly by provider events

Acceptance criteria

Close only when:

1. provider event intake is specified or implemented;
2. exact-lease updates are proven;
3. stale provider updates cannot overwrite SSOT item refs;
4. conflicts are retained under conflict refs;
5. all allowed/rejected updates emit receipt refs;
6. provider events cannot write accepted meaning refs;
7. retention/readback/restore proof exists;
8. rollback path exists;
9. GitHub or any remote forge remains a provider surface, not accepted meaning authority;
10. roccho-dev/adrs#191 can cite this as a readiness dependency.

Initial status

A local proof exists for single-run GitHub issue/PR provider-event reconciliation into SSOT refs, including stale conflict handling and accepted-ref write prohibition.

That proof does not prove a live webhook daemon, GitHub App delivery route, or production self-hosted Git server integration. Those remain in scope here.

[roccho-dev]

ADRS companion issue

ADRS-side dependency contract has been opened:

• roccho-dev/adrs#192 — Define refs sync readiness dependency for ADRS replacement

Boundary:

• adrs#192 defines what #191 requires from this mechanism.
• ops#35 owns the effectful sync / retention / restore / readback mechanism.
• adrs#191 consumes the result as readiness evidence, without implementing transport.