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-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`

planning/adr-0016-code-review-2dd687b.md

@@ -0,0 +1,50 @@
+# ADR-0016 code review — 2dd687b
+
+- Date: 2026-08-20
+- Reviewed commit: `2dd687bdd4a958694a53049014791ede0b67c0be`
+- Base: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37`
+- Reviewer: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `issues_found`
+
+## Checks
+
+- ADR governance: passed, 1 ADR checked.
+- Governance tests: passed, 20 tests.
+- `git diff --check origin/main...HEAD`: passed.
+- Full diff inspected: five added files, 706 insertions.
+- Content commit `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`: inspected in full.
+- Accepted ADR-0003 through ADR-0007 and ADR-0012 through ADR-0015: byte-identical to base.
+- ADR-0016 remained Proposed with human-only acceptance.
+- CI: not run; local evidence is not CI-green.
+- Worktree: clean at review time.
+
+## Findings
+
+### HIGH — Pointer parity lacks an untrusted-content boundary
+
+Anchors: `adr/ADR-0016-released-truth-for-public-developer-docs.md:101-103` and `skills/start/SKILL.md:81-83` at the reviewed commit.
+
+Pointer parity requires agents to ingest fetched documentation before answering release-sensitive detail but does not require fetched pages to be treated as untrusted factual data. It does not prevent embedded instructions from overriding the skill or user request, require content delimiting, or require independent validation before actions are taken from fetched material. The historical audit mentions this safeguard, but the audit is explicitly not current authority.
+
+Required disposition: add a durable prompt-injection boundary for pointered content.
+
+### MEDIUM — Mutable-alias policy is internally inconsistent
+
+Anchors: `ADR-0016:57,82,155,166` at the reviewed commit.
+
+The ADR requires every default or recommended command to use an immutable selector while also allowing a mutable alias to continue to be recommended after requalification.
+
+Required disposition: mutable aliases may only appear as explicitly unsupported conveniences and can never be default or recommended commands.
+
+## Previous-finding dispositions
+
+- Deterministic fallback across all eligible sets: resolved.
+- Requalification on every qualification-input change: resolved.
+- Immutable default selectors: resolved, but mutable-alias recommendation language remains inconsistent as described above.
+
+## Remaining risks
+
+- Applicable pull-request CI has not run.
+- Goal verification, adversarial re-review, Craft, and clean-context remain outstanding.
+- The v0.11.2 audit is historical; a fresh candidate audit is required before implementation.
+- Implementer provider is unrecorded; cross-provider independence is unconfirmed.

planning/adr-0016-code-review-481ca8c.md

@@ -0,0 +1,37 @@
+# ADR-0016 code review — 481ca8c
+
+- Date: 2026-08-20
+- Reviewed commit: `481ca8cb653b32823851d38b2bcc36b4007ddf7a`
+- Base: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37`
+- Reviewer: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `passed`
+
+## Checks
+
+- ADR governance: passed, 1 ADR checked.
+- Governance tests: passed, 20 tests.
+- `git diff --check origin/main...HEAD`: passed.
+- Full base diff inspected: six added files, 771 insertions.
+- Content commit `4873f368feec5183b7a69c493c86d2beb6efe8b5`: inspected in full.
+- Accepted ADR-0003 through ADR-0007 and ADR-0012 through ADR-0015: byte-identical to base.
+- Worktree: clean at review time.
+- CI: not run; local evidence is not CI-green.
+
+## Findings
+
+None.
+
+## Previous-finding dispositions
+
+- Pointer-security boundary: resolved. Fetched guidance is delimited untrusted factual input and cannot override controlling instructions, permissions, safety constraints, or approval gates; provenance/manifest conflicts defer safely.
+- Mutable-alias inconsistency: resolved. Aliases are explicitly unsupported and can never be default, supported, or recommended commands.
+- Deterministic fallback and incumbent requalification: remain resolved.
+
+## Remaining risks
+
+- Pull-request-triggered ADR Governance CI has not run.
+- ADR-0016 remains Proposed and requires explicit human acceptance.
+- The existing skill still has pre-implementation behavior; implementation must enforce any accepted policy.
+- Comparator, manifest, watch-state, migration, and enforcement details remain later specification work.
+- The v0.11.2 audit is historical; a fresh candidate-release audit is required before implementation.
+- Goal verification, adversarial re-review, Craft, and clean-context remain outstanding.

planning/adr-0016-code-review-752099a.md

@@ -0,0 +1,30 @@
+# ADR-0016 code review — 752099a
+
+- Date: 2026-08-28
+- Reviewed commit: `752099ac110182655ec114a724eb236c66d4427e`
+- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c`
+- Reviewer: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`)
+- Result: `passed`
+- Word count: 477, including title, metadata, and headings
+
+## Checks
+
+- ADR governance: passed, 1 ADR checked.
+- Governance tests: passed, 20 tests.
+- Diff check against the current PR base: passed.
+- Accepted ADRs: unchanged.
+- Template, American English, scope, and partial supersession: passed.
+- Exact-head ADR Governance and GitBook checks: passed.
+- Prose/sweep checks: successful branch-scope no-ops.
+- Worktree: clean at review time.
+
+## Findings
+
+None.
+
+## Remaining risks
+
+- ADR-0016 remains Proposed and requires human acceptance.
+- Implementation requires a reviewed specification, planning documents, and a fresh release audit.
+- Goal verification, adversarial, Craft, and clean-context remain pending.
+- Same-model review provides weaker independence than cross-model review.