docs(adr): adopt released truth for public documentation

adr/ADR-0016-released-truth-for-public-developer-docs.md

@@ -0,0 +1,78 @@
+# ADR-0016: Public documentation describes obtainable releases
+
+- **Status:** Accepted
+- **Acceptance:** Prospective — accepted by Jim Collinson as decision owner after review of PR #98 on 2026-08-31.
+- **Date:** 2026-08-12
+- **Decision owners:** Jim Collinson
+- **Reviewers:** Jim Collinson
+- **Supersedes:** ADR-0003 (public source selection only); ADR-0004 and ADR-0006 (public provenance advancement only)
+- **Superseded by:** none
+- **Related:** `planning/released-antd-v0.11.2-audit.md`; PR #98
+
+## Context
+
+Public developer documentation is a promise about software developers can obtain and use.
+
+Default-branch code may be unreleased, unavailable through supported installation routes, or reverted. Documentation based on it can describe a product the public cannot obtain.
+
+A stable release is the stake in the ground against which public documentation is written and verified.
+
+## Decision Drivers
+
+- Developers must be able to obtain the software the documentation describes.
+- Public claims must have stable, auditable provenance.
+- Known release defects and limitations must be represented honestly.
+
+## Considered Options
+
+1. Document the latest merged source.
+2. Document stable, publicly obtainable releases. Chosen.
+
+## Decision
+
+Public developer documentation will describe only stable or general-availability software available through supported public distribution or installation routes.
+
+The documentation will use an explicit release baseline. For a multi-component product, it identifies compatible released components, exact shipped dependencies, and the compatible deployed Autonomi Network state where relevant.
+
+Every technical claim must be supported by the baseline release, its exact shipped dependencies, or verified behavior against the compatible deployed network.
+
+A documentation baseline advances only through reviewed promotion of a public release. Unreleased code may inform future documentation but cannot support default public claims.
+
+Known defects are part of released truth. Affected capabilities must be described with their limitations and safe alternatives, or must not be presented as working.
+
+If no released software supports a claim or task, the documentation must state that limitation rather than infer support from source.
+
+Pre-release documentation, if published, must be clearly separated from the default public documentation.
+
+This decision governs public documentation in this repository. It does not govern a separate developer skill.
+
+Implementation details and sequencing belong in a reviewed specification and planning documents.
+
+## Consequences
+
+### Positive
+
+- Public documentation corresponds to obtainable software.
+- Releases provide stable and reproducible verification boundaries.
+- Defects cannot be hidden by newer unreleased source.
+
+### Negative / Trade-offs
+
+- Documentation may intentionally lag merged development.
+- Promoting a release baseline requires verification work.
+
+### Neutral / Operational
+
+- Default branches remain useful for preparing future documentation.
+
+## Validation
+
+- Every public technical claim resolves to exact release, shipped-dependency, or verified deployed-network evidence.
+- Documented installation routes resolve to the intended public artifacts.
+- Unreleased source cannot advance the public documentation baseline.
+- Known broken or unverified capabilities are not presented as working.
+- Every baseline change leaves a reviewed release-promotion record.
+
+## Notes for AI-assisted work
+
+AI tools helped draft this ADR. Jim Collinson accepted it through PR #98 on 2026-08-31. The PR remains reviewable until merge; later changes require a superseding ADR.

planning/adr-0016-acceptance-adversarial-e2d54b2.md

@@ -0,0 +1,38 @@
+# ADR-0016 acceptance-record adversarial review — e2d54b2
+
+- Date: 2026-08-31
+- Reviewed head: `e2d54b26e5d510419885345e22a2374d46aeb710`
+- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `NOT-READY`
+
+## Findings
+
+### HIGH — Live PR body contradicted acceptance and merge authorization
+
+The live PR body contradicted acceptance and merge authorization and had stale head, count, and merge-ref evidence.
+
+Disposition: the orchestrator corrected the live PR body before the evidence-reconciliation commit.
+
+### MEDIUM — Living records and branch-local reports lagged completed evidence
+
+`planning/STATE.md` and `planning/gsd-adr-0016-checkpoint.md` still marked completed code review, verification, and CI pending and lacked branch-local code-review and 7/7 verification reports.
+
+Disposition: the evidence-reconciliation commit updates both living records and adds the missing reports.
+
+### LOW — Required-check wording obscured the CI distinction
+
+Generic `required checks` wording obscured that ADR Governance is process-required but not GitHub branch-protection-required. GitHub branch protection requires only prose, sweep, and sweep SHA reachability, all of which were green `not applicable` scope-gate no-ops here.
+
+Disposition: the evidence-reconciliation commit uses explicit process-required and GitHub branch-protection-required wording.
+
+## Content and governance
+
+No content or governance failure was found. ADR-0016's decision remained unchanged, the ADR contained 497 words, local checks passed, and alignment with ADR-0015 was correct.
+
+## Independence
+
+This review used OpenAI GPT-5.6-sol, the same provider and model as the earlier review. The implementer provider is unrecorded, so independence evidence is weaker.
+
+## Remaining merge conditions
+
+Final adversarial rerun and Craft Review are mandatory after the evidence-reconciliation commit. Neither has passed yet.

planning/adr-0016-acceptance-code-review-e2d54b2.md

@@ -0,0 +1,19 @@
+# ADR-0016 acceptance-record code review — e2d54b2
+
+- Date: 2026-08-31
+- Reviewed range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`
+- Result: `passed`
+
+## Checks
+
+- ADR governance: passed, 1 ADR checked.
+- Governance tests: passed, 20/20 tests.
+- Diff and protected scope: passed.
+- Only the three expected files changed.
+- ADR-0016 changed only Status, Acceptance, and the final note.
+- ADR-0016's decision remained unchanged and the ADR contained 497 words.
+- Acceptance, merge authorization, the final-head CI condition for process-required ADR Governance plus GitHub branch-protection-required checks, implementation prohibition, clean-context waiver, and default-branch immutability were coherent.
+
+## Findings
+
+None.

planning/adr-0016-acceptance-verification-e2d54b2.md

@@ -0,0 +1,26 @@
+# ADR-0016 acceptance-record verification — e2d54b2
+
+- Date: 2026-08-31
+- Reviewed range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`
+- Result: `passed`
+- Score: 7/7 goals verified
+
+## Verified
+
+- The human-acceptance basis names Jim Collinson, PR #98, and 2026-08-31.
+- ADR-0015 permits an Accepted-status transition within an ADR's introducing pull request and places Accepted-ADR immutability at the default branch.
+- Only authorized scopes changed.
+- ADR governance passed with 1 ADR checked.
+- All 20 governance tests passed.
+- The diff check passed.
+- At review time the pre-merge condition was that the remote needed the acceptance commits. That condition has since been satisfied, and CI associated with `e2d54b26e5d510419885345e22a2374d46aeb710` is green.
+
+## CI associated with e2d54b2
+
+- Process-required ADR Governance run `33392124485`, job `99487983002`, was associated with head `e2d54b2` and ran on clean synthetic merge ref `c53dfc6d1b422099ed5dadb2406f0d8876409920`; checkout, all 20 tests, and governance passed.
+- GitHub branch-protection-required prose run `33392124442`, job `99487983034`, sweep run `33392124448`, job `99487983102`, and sweep SHA reachability run `33392124434`, job `99487982641`, all passed as `not applicable` scope-gate no-ops with main validation skipped.
+- Both GitBook statuses passed.
+
+## Findings
+
+None.

planning/adr-0016-adversarial-d18a63b.md

@@ -0,0 +1,36 @@
+# ADR-0016 adversarial review — d18a63b
+
+- Date: 2026-08-28
+- Reviewed commit: `d18a63b62f3e7cfdc1e2d72863fa14fc2b60de82`
+- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c`
+- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `READY-WITH-NITS`
+
+## Findings
+
+No CRITICAL, HIGH, or MEDIUM findings.
+
+### LOW — Validation narrowed the deployed-network evidence path
+
+The decision allowed release, shipped-dependency, or verified deployed-network evidence, while one validation bullet referred only to released provenance. This was non-blocking because the decision remained clear. It was corrected in follow-up content commit `dfe2161`.
+
+### LOW — PR body lagged final verification
+
+The PR body still called completed reverification pending. This understated readiness rather than engineering a false green and was corrected after review.
+
+## Durable-decision result
+
+The concise decision survived attacks on obtainable releases, coherent provenance, reviewed promotion, unreleased-source exclusion, honest defects, preview separation, skill exclusion, implementation deferral, and partial supersession.
+
+## Evidence integrity
+
+- Exact local/remote head and clean worktree confirmed.
+- ADR remained 477 words at review time and unchanged from the tightening content commit.
+- ADR governance, 20 tests, diff check, exact-head CI, and GitBook checks passed.
+- Accepted ADRs were byte-identical to the current base.
+- Prose/sweep checks were scope-gate no-ops.
+- Craft and clean-context had not yet run.
+
+## Independence
+
+This used the same model/provider as other concise-review lanes. No second provider was available, so independence evidence is weaker.

planning/adr-0016-adversarial-dfd14da.md

@@ -0,0 +1,44 @@
+# ADR-0016 adversarial review — dfd14da
+
+- Date: 2026-08-20
+- Reviewed commit: `dfd14dabcbec4706449ae6af1270328ed6dc26af`
+- Current PR base: `487866a249fcb5ad7d8dd7829c017ed63d421343`
+- Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98
+- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `NOT-READY`
+- Independence: same model/provider as prior review lanes; implementer provider unrecorded, so evidence is weaker
+
+## Blocker
+
+### HIGH — Qualification is ambiguously global to the release set and local to individual journeys
+
+Anchors at the reviewed commit: `adr/ADR-0016-released-truth-for-public-developer-docs.md:43,73,87,89,99,180`.
+
+The ADR selects one coherent release set and requires its mandatory baseline to pass across every default or recommended interface. Elsewhere, it allows an incumbent to remain supported only for qualifying journeys and says affected guidance can withdraw one journey.
+
+Those rules permit conflicting outcomes. If one active set supports recommended SDK and CLI journeys and the SDK store journey later fails, the whole set can be disqualified by the mandatory baseline, while the journey-local clauses allow only SDK guidance to be withdrawn and CLI support to remain.
+
+Required decision: make qualification and fallback unambiguously either global to the coherent release set or journey-local with per-journey incumbents reconciled against the one-manifest/one-coherent-set invariant. Then align mandatory-baseline, incumbent, no-baseline, validation, and verification language.
+
+## Low finding
+
+The committed state/checkpoint described exact-head CI as pending after it had passed and still called the historical branch point `origin/main`. Final records must distinguish branch point from current PR base and state that prose/sweep checks succeeded as scope-gate no-ops rather than substantive coverage.
+
+## Evidence integrity
+
+- Local and remote head matched `dfd14da`; worktree was clean.
+- Current PR base was `487866a`; PR was mergeable but behind base, with no conflicts in the eight changed files.
+- Exact-head ADR Governance, GitBook, and preview checks were green.
+- `prose-guard`, `sweep-guard`, and `sweep-sha-reachability` succeeded but their substantive steps were skipped because the branch name was outside their prose/sweep scopes.
+- No branch commit changed CI, tests, scripts, gates, rendered docs, skill content, registries, manifests, or Accepted ADRs.
+- ADR content had not changed since `4873f36`; later commits were review/state evidence.
+- The v0.11.2 audit remained explicitly historical and was not used as v0.12.0 implementation evidence.
+- Craft and clean-context remained pending.
+
+## Test-quality note
+
+ADR governance and 20 governance tests passed but exercise structure and Accepted-ADR immutability, not qualification granularity. The 10/10 goal verification did not exercise the conflicting mandatory-baseline scenario and must be updated after the decision.
+
+## Single required decision
+
+Define one qualification and fallback unit—global release set or per journey—and make all related clauses agree.

planning/adr-0016-adversarial-ef646b9.md

@@ -0,0 +1,61 @@
+# ADR-0016 adversarial review — ef646b9
+
+- Date: 2026-08-20
+- Reviewed commit: `ef646b9f7d360a5ef2597d3b77cfc08cedb5fd61`
+- Current PR base: `487866a249fcb5ad7d8dd7829c017ed63d421343`
+- Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98
+- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `NOT-READY`
+- Independence: same model/provider as prior lanes; implementer provider unrecorded, so evidence remains weaker
+
+## Findings
+
+### HIGH — Same-interface wording permits a non-existent composite SDK route
+
+Anchors: `adr/ADR-0016-released-truth-for-public-developer-docs.md:77,80`, `CLAUDE.md:139,142`, and the binding/transport differences in `planning/released-antd-v0.11.2-audit.md:98-114` at the reviewed commit.
+
+The ADR forbids combining different top-level interfaces, but both Python REST store and Go gRPC retrieve can be labeled SDK. Without route continuity below the top-level interface, incompatible bindings or transports could be combined to fabricate a complete route.
+
+Required disposition: every dependent step in a complete route must use one concrete binding, transport, installation identity, runtime/configuration, and carried state where applicable. Detailed identifier schema remains specification work.
+
+### HIGH — ADR-0011's unconditional SDK-primary stance is changed but not superseded
+
+Anchors: `adr/ADR-0011-information-architecture-and-content-design.md:47,50,79` and `ADR-0016:106,132,159` at the reviewed commit.
+
+ADR-0016 permits SDK journeys to become unavailable while CLI remains the only recommended complete route, but it says ADR-0011 remains intact and omits ADR-0011 from `Supersedes`.
+
+Required disposition: precisely supersede ADR-0011's unconditional primary-interface stance and replace it with an evidence-conditioned rule. Preserve the rest of ADR-0011.
+
+### MEDIUM — Truth-table evidence omitted concrete within-SDK continuity
+
+The branch-local code-review and verification reports list scenario names but do not provide concrete route identities and missed the cross-binding/transport case.
+
+Required disposition: commit an explicit truth table with concrete binding, transport, installation, runtime/configuration, state-continuity inputs, expected results, actual clause derivation, and ADR-0011 consequence.
+
+### LOW — State, checkpoint, and PR evidence were stale
+
+Records still named older reviews and CI heads, and the PR body called pre-amendment reports final. Reconcile them with the current exact head and distinguish scope-gated no-op checks.
+
+### LOW — Historical v0.11.2 defect used present tense
+
+Scope the gRPC issue sentence explicitly to v0.11.2 and use past tense because current base includes the fix and issue #233 is closed.
+
+## Truth-table challenge
+
+All reviewed scenarios passed except:
+
+- Python SDK store plus a different SDK binding/transport retrieve: ambiguous and could falsely pass.
+- SDK unavailable while CLI is recommended: allowed by ADR-0016 but conflicts with Accepted ADR-0011.
+
+## Evidence integrity
+
+- Exact local/remote head and clean worktree confirmed.
+- Exact-head ADR Governance and GitBook checks passed.
+- Prose/sweep checks were scope-gate no-ops.
+- No implementation, mechanism, skill, docs, manifest, or Accepted ADR changed.
+- Historical audit limitations remained explicit.
+- Craft and clean-context remained pending.
+
+## Single most important correction
+
+Define complete-route continuity below the four top-level interface labels so incompatible SDK bindings or transports cannot fabricate an end-to-end route.

planning/adr-0016-clean-context-50f4462.md

@@ -0,0 +1,16 @@
+# ADR-0016 clean-context dispatch — 50f4462
+
+- Date: 2026-08-28
+- Requested commit: `50f4462`
+- Requested reviewer: controlled Claude Fable panel lane
+- Result: `Blocked before inference`
+
+Milestone A activation was present in `planning/STATE.md`, but the required caller-owned `brief.md` did not exist under the exact disposable panel root. The orchestrator's outer filesystem permission refused creation of that root and brief. Chat text cannot substitute for the required regular stdin file.
+
+The panel could not create or attest the caller-owned brief. Claude CLI and inference were not invoked. No session, provider/model attribution, findings, or persisted output exists.
+
+Required next action: explicitly authorize creation of one disposable root and regular `brief.md` under the named `/var/.../opencode/gsd-panel-<UUID>` path, then issue a fresh dispatch with all fields.
+
+models: provider=not-observed · model=not-resolved · duration=unknown
+
+claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved

planning/adr-0016-clean-context-dcf7c8c.md

@@ -0,0 +1,14 @@
+# ADR-0016 clean-context review — dcf7c8c
+
+- Date: 2026-08-28
+- Requested commit: `dcf7c8c5ca5199f174b5d493c3a75215933e3f4b`
+- Requested reviewer: controlled Claude panel Fable lane
+- Result: `Blocked`
+
+The reviewer was not invoked. The panel remains inactive for normal and ad-hoc use until Jim records the separate Milestone A activation verdict. The earlier Slice 2 proof authorization cannot be reused.
+
+No substitute reviewer was used and no inference command was attempted.
+
+Evidence line:
+
+`claude=official claude CLI Fable review family (Anthropic), BLOCKED: panel activation/dispatch authorization absent; no reviewer inference attempted`