Skip to content

Decision record · ADR

ADR-0008: publish head-only with site-fact exclusion

Status: accepted | Date: 2026-07-04

References: RFC-0005:C-EVIDENCE

InferLab is being published to GitHub. The internal history predates the publication decision and provably retains since-scrubbed site facts (an internal hostname survived in pre-scrub commit text even after the tracked tree was cleaned). The standing operator constraint excludes usernames, hostnames, internal paths, and real hardware identities from anything published, while execution records remain intentionally unredacted local evidence per the records clause of the evidence contract. A durable rule is needed for what may ship and who performs the shipping; until now that policy lived only in a work item. Amended 2026-07-05: preparing the first publication surfaced that the tracked tree itself carries the full internal work-item corpus and the specification revision history, so the decision gained a content-filter policy recording which tree content may ship. A same-day follow-up amendment settles the ongoing synchronization model between the development repository and the public mirror, which the original decision had deferred.

Publication and synchronization follow one model: the private development repository is the sole source of truth, and the public repository is a filtered snapshot mirror of it.

  • History: publication is HEAD-only. Public history is initialized from the current HEAD and the internal lineage is never pushed; the public repository is never configured as a remote of the development repository, so the never-push rule holds by topology rather than by discipline.
  • Content: the published tree is a filtered export of HEAD, not the tracked tree verbatim. Raw governance artifacts (gov/), work-item renders (docs/work/), and the governance-workflow agent rules file (AGENTS.md) never enter public git, because they carry the internal work-item narrative and the specification revision history. Rendered specifications do ship: govctl render rfc and govctl render adr run before every export, docs/rfc plus docs/adr publish the current clause and decision state, and the export strips the rendered RFC changelog section: the per-version change narrative stays private, while the specification version header and per-clause Since markers still ship. The export fails loudly if the expected changelog section is absent. Published prose speaks in public terms: internal generation labels, project codenames, episode names, and internal-process narration (review-round numbering, tracker vocabulary, pointers into private artifacts) do not ship; decision records keep their decision-context narrative, stated in public terms. Because the public tree carries no gov/, the public CI workflow carries no governance job; governance checks remain local.
  • Scan: before any push or tag, the operator scans the exported tree for site facts — usernames, hostnames, internal paths, and real hardware identities — and clears every hit.
  • Acts: publication acts are initiated by the operator, never by tooling or agents acting autonomously: the operator creates the public repository, pushes snapshots, and pushes tags. A workflow triggered by the operator’s tag push executes the mechanical consequences of that act inside the repository’s own release — building the artifacts, creating the GitHub release, uploading its assets — because the irreversible decision was the operator’s tag. Package-registry publication (the Python package index, the crates registry) is never executed by automation: the operator publishes locally built, gate-verified files from the development machine — the same flow for both registries — and attaches the same wheel files to the GitHub release as assets, so every transport carries one local build. (Amended 2026-07-06 to state the initiation reading the release workflow has relied on since the first release and to fix registry publication as manual; ADR-0009 relies on both.)
  • Ongoing flow: every synchronization — release or not — repeats render, filtered export, and scan; the filtered export lands in a separate clone of the public repository, where the operator commits and pushes it as a snapshot commit, tagged only for releases. No content originates on the public repository: external contributions land locally first — the operator applies the PR diff to the development repository and commits it with contributor attribution — and the PR merges publicly only after that backport lands. Before every snapshot push the operator reviews the public-side diff against the refreshed public state — a stale clone would silently miss a freshly merged contribution, so the clone is fast-forwarded from the public remote before the export lands; every change must be explained by local work, and an unexplained reversion means a missing backport and stops the push, because the snapshot overwrite would otherwise silently discard the public-side change.

Positive:

  • The leak surface for publication is exactly the filtered export of the current tree, which the pre-push scan covers; pre-scrub history cannot ship by construction.
  • The operator-performs-publication rule makes irreversible outward acts a human decision every time.
  • Keeping the public repository out of the development repository’s remotes makes an accidental push of the internal lineage mechanically impossible, not merely forbidden.

Negative:

  • The public repository carries no development provenance; consumers see squashed state. The internal lineage is retained locally, so a deliberate public-history migration remains possible if ever wanted.
  • Every synchronization repeats the scan; skipping it silently would reopen the leak class, so the snapshot procedure must keep it explicit.
  • The tracked tree and the published tree differ by a fixed exclusion set; every export must apply the same filter, so the snapshot procedure keeps the filter explicit alongside the scan.
  • Public CI cannot validate governance conformance because the public tree carries no gov/; drift between the public tree and the governed source is only catchable locally, so local govctl check and the render step gate every publication cycle.
  • The changelog strip is a structural transformation of render output; a render-format change could silently ship the revision history, so the export fails loudly when the expected changelog section is absent.
  • A public-side change that is not backported before the next snapshot is silently discarded by the export overwrite; the pre-snapshot reversion review is the guard, and it stays manual until contribution volume justifies tooling.

Neutral:

  • Internal governance artifacts (work items, loop evidence) keep the full narrative privately; nothing about internal history changes.
  • The public sees only the current clause and decision state, never how the specification evolved; rendered docs/rfc and docs/adr are refreshed by govctl render rfc and govctl render adr before every export.
  • Public history is a chain of snapshot commits whose pairwise diffs are ordinary content diffs; contributor credit survives through public PR merges and contributor attribution in the local commits.

HEAD-only publication of a filtered export with a pre-publish site-fact scan: public history is initialized from the current HEAD; the export excludes raw governance artifacts, work-item renders, and AGENTS.md while shipping rendered specifications with the RFC changelog section stripped; the tree is scanned for site facts before any push or tag; ongoing synchronization keeps content authority local, with backport-before-merge for external contributions and a reversion review before every snapshot push (accepted)

Section titled “HEAD-only publication of a filtered export with a pre-publish site-fact scan: public history is initialized from the current HEAD; the export excludes raw governance artifacts, work-item renders, and AGENTS.md while shipping rendered specifications with the RFC changelog section stripped; the tree is scanned for site facts before any push or tag; ongoing synchronization keeps content authority local, with backport-before-merge for external contributions and a reversion review before every snapshot push (accepted)”
  • Pros: the leak class is bounded by what a HEAD scan can see; no rewrite tooling, no history archaeology
  • Cons: the public repository starts without provenance; the internal governance records keep the narrative, every synchronization is a manual pipeline, and un-backported public-side changes face a clobber hazard guarded only by the manual reversion review

Full-history publication after history rewriting (filter-repo or equivalent) (rejected)

Section titled “Full-history publication after history rewriting (filter-repo or equivalent) (rejected)”
  • Pros: preserves public provenance
  • Cons: rewrites are error-prone and unverifiable at scale; every retained commit message and blob must be individually cleared; local collaboration state is invalidated
  • Rejected because: rewrites cannot be verified clean at the required confidence; every retained commit message and blob would need individual clearance

Publish the history as-is, relying on the tracked-tree scrub (rejected)

Section titled “Publish the history as-is, relying on the tracked-tree scrub (rejected)”
  • Pros: zero preparation
  • Cons: provably ships since-scrubbed site facts in commit text
  • Rejected because: provably ships since-scrubbed site facts in commit text

Publish the tracked tree verbatim, governance artifacts included (rejected)

Section titled “Publish the tracked tree verbatim, governance artifacts included (rejected)”
  • Pros: the export step is a plain copy; the local and public trees are identical
  • Cons: ships the internal work-item corpus and the full specification revision history that the operator explicitly keeps private
  • Rejected because: the tracked tree carries exactly the content the publication policy exists to keep private

Ship raw gov/ TOML sources instead of rendered specifications (rejected)

Section titled “Ship raw gov/ TOML sources instead of rendered specifications (rejected)”
  • Pros: the public spec is the governed source of truth itself, with no render step in the flow
  • Cons: rfc.toml embeds the full changelog and gov/work is inseparable from the corpus, so raw shipping cannot exclude the revision history; TOML sources are also a worse reading surface than rendered markdown
  • Rejected because: raw governance sources cannot ship the current-state spec without the private revision narrative

Continue development on the public lineage after the first publication, with the public repository as an ordinary remote (rejected)

Section titled “Continue development on the public lineage after the first publication, with the public repository as an ordinary remote (rejected)”
  • Pros: ordinary push/pull synchronization with no export step after the first release
  • Cons: either the tracked governance artifacts flow public or they must be untracked, destroying the local governance audit trail; the internal lineage also retains pre-scrub site facts, so sharing lineage reopens the leak class
  • Rejected because: incompatible with both the privacy bar and locally tracked governance

Close external PRs without merging and re-author every contribution internally (rejected)

Section titled “Close external PRs without merging and re-author every contribution internally (rejected)”
  • Pros: the strictest single-source model, with no clobber hazard at all
  • Cons: contributors lose merged status and public credit; backport-before-merge plus the reversion review already preserves local authority with credit intact
  • Rejected because: worse contributor experience purchases no additional authority

Merge external PRs publicly first and pull them back into the development repository afterwards (rejected)

Section titled “Merge external PRs publicly first and pull them back into the development repository afterwards (rejected)”
  • Pros: the conventional OSS mirror flow; contributors see instant merges
  • Cons: public main holds changes the development repository lacks until the pull-back happens; a snapshot push inside that window silently discards them
  • Rejected because: it widens exactly the un-backported clobber window the reversion review exists to close