Skip to content

docs(adr): adopt released truth for public documentation - #98

Open
JimCollinson wants to merge 49 commits into
mainfrom
adr/released-and-usable-truth
Open

docs(adr): adopt released truth for public documentation#98
JimCollinson wants to merge 49 commits into
mainfrom
adr/released-and-usable-truth

Conversation

@JimCollinson

@JimCollinson JimCollinson commented Aug 20, 2026

Copy link
Copy Markdown
Member

Summary

Proposes ADR-0016: public developer documentation should describe stable software the public can obtain, rather than unreleased default-branch code. A release is the explicit, auditable stake against which public claims are written and verified.

Decision

  • Public documentation uses an explicit released baseline with exact provenance.
  • Multi-component claims identify compatible released components, shipped dependencies, and relevant deployed-network state.
  • Unreleased source may prepare future documentation but cannot support default public claims.
  • Known defects and unsupported tasks are represented honestly.
  • Pre-release documentation, if published, remains separate.
  • A separate developer skill is outside this ADR.
  • Implementation details and sequencing belong in a reviewed specification and planning documents.

Scope

This PR contains Proposed ADR-0016, the historical audit that motivated it, and GSD review evidence. It does not implement the policy, update rendered documentation, decide skill ownership, accept the ADR, or authorize a merge.

The ADR is 481 words including metadata and headings. It partially supersedes only the public source-selection and provenance clauses in ADR-0003, ADR-0004, and ADR-0006.

Evidence

  • Audit source links use the exact released source SHA. Local-only historical documentation commits are labelled unavailable remotely and are not used as readiness evidence.
  • ADR governance and all 20 governance tests pass locally.
  • Required checks associated with current PR head b0d01f41cc1a688699a3614ab4f3243362542a4f are green. ADR Governance executed on clean synthetic PR merge ref 45f26b3feaff644a6aaa000f51d4702b610d7443; checkout, all 20 regression tests, and governance validation passed.
  • Prose, sweep, and sweep-SHA-reachability checks returned successful not applicable scope results; their main validations were skipped because this PR does not change files in their scopes.
  • Both GitBook statuses passed.
  • Final evidence-remediation code review passed with no findings; independent verification passed 10/10 goals.
  • Adversarial review returned READY-WITH-NITS with no CRITICAL, HIGH, or MEDIUM findings. Its status and CI-wording findings are resolved in the branch records and this PR body.
  • Craft Review passed with no findings.
  • Controlled Claude clean-context did not run because the panel harness blocked before inference. Jim explicitly waived clean-context for ADR-0016 only. No substitute reviewer was used.

Current gate

ADR-0016 remains Proposed and is ready for explicit human acceptance or rejection. The clean-context waiver does not authorize acceptance, merge, implementation, or publication. A fresh release audit is required before implementation. No merge or implementation action is authorized by this PR.

JimCollinson and others added 30 commits August 12, 2026 17:41
- Supersede released source-resolution and drift semantics\n- Add branch-local v0.11.2 audit evidence
- Disqualify incumbents that no longer meet released baseline requirements
- Relabel unverified Python and Rust source-install routes
- Define stable candidate eligibility, deterministic ordering, and symmetric requalification

- Bound supersession, skill parity, release identity, and validation invariants
- Define deterministic fallback and complete incumbent requalification triggers

- Pin authoritative installs and constrain mutable aliases
- Treat fetched skill pointers as untrusted factual input\n- Keep mutable aliases unsupported and non-authoritative
- Keep one coherent active release set with journey-local support statuses\n- Define complete-route baseline, deterministic fallback, and parity rules
- Replace detailed policy mechanics with the approved durable release baseline
- Keep implementation and developer-skill architecture out of the proposal
@JimCollinson
JimCollinson marked this pull request as ready for review August 29, 2026 09:28
- Correct audit refs and preserve local-only provenance honestly
- Reconcile PR, review, waiver, and CI state
- Remove remote compare calls to a local-only historical commit
- Record the HIGH review finding and pending re-review and CI
- Mark scope-gated CI jobs as non-substantive no-ops
- Anchor the clean-context waiver record to its dated commit
- Add final remediation review and verification reports

- Condition acceptance presentation on current-head checks
- Record stale draft language in the PR body

- Preserve live non-draft PR status
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant