docs(adr): adopt released truth for public documentation

planning/STATE.md

@@ -0,0 +1,84 @@
+# GSD State
+
+## Current Position
+
+- Phase: released-truth source-of-truth decision
+- Plan: supersede ADR-0003 before documentation remediation
+- Task: remediate complete-route continuity and ADR-0011 supersession
+- Status: adversarial NOT-READY; attended checkpoint
+- Mode: attended
+- Branch: `adr/released-and-usable-truth`
+- Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98
+- Branch point: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37`
+- Current draft-PR base: `origin/main` at `487866a249fcb5ad7d8dd7829c017ed63d421343`
+- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`; pointer-security correction `4873f368feec5183b7a69c493c86d2beb6efe8b5`; journey-local amendment `fb00f10b5620ce502345fdbdb1689ac7c0014d98`
+- Implementation: not started; ADR acceptance remains human-only
+
+## Decision Intent
+
+- Public rendered developer documentation and the published developer skill should describe released, publicly obtainable, compatible, capability-evidenced usable truth.
+- Known released defects and safe alternatives are part of that truth.
+- Moving default branches prepare the next release; they do not silently advance the public documentation.
+- `target-manifest` remains pre-release/preview truth; `current-merged-truth` retires from the default public surface.
+
+## Review State
+
+- First remediation commit `735091d` addresses the initial adversarial and Craft findings: ADR-0004 source-resolution/drift semantics, seven durable promotion-evidence groups, branch-local audit evidence, docs/skill capability consistency, explicit older-baseline guidance, Prospective Acceptance metadata, and American English.
+- Second correction commit `57ec56c` disqualifies withdrawn, insecure, incompatible, or baseline-noncompliant incumbents and relabels Python/Rust source-install routes as metadata-identified but not clean-install/runtime verified.
+- Structural validation after the second correction: ADR governance passed with 1 ADR checked; 20 governance tests passed; `git diff --check origin/main...HEAD` passed; worktree was clean.
+- Final independent code review at `5dbecd5`: passed with no findings. ADR governance passed; 20 governance tests passed; `git diff --check origin/main...HEAD` passed; Accepted ADRs remained byte-identical.
+- Goal verification at `5dbecd5`: passed, 7/7 goals verified. No scope gaps or unauthorized implementation found.
+- Adversarial re-review at `ff9761a`: `NOT-READY` with four HIGH and three MEDIUM findings.
+  - HIGH: candidate admission does not explicitly exclude draft/pre-release artifacts or apply symmetric safety/security qualification.
+  - HIGH: deterministic newest-candidate discovery/ordering and continuing incumbent requalification across releases, artifacts, advisories, and deployed-network changes are not durable invariants.
+  - HIGH: supersession is incomplete because released-only provenance conflicts with Accepted ADR-0006 and ADR-0014, with an impact on ADR-0013's stamp-refresh mechanism.
+  - HIGH: the repository has an applicable PR-triggered CI arbiter at `.github/workflows/adr-governance.yml`; no CI run exists for this unpushed branch.
+  - MEDIUM: docs/skill capability parity is ambiguous against ADR-0013's pointer-based skill model.
+  - MEDIUM: public release identity requirements do not distinguish distributable artifacts from exact transitive dependency refs without their own release.
+  - MEDIUM: code-review and goal-verification claims covered commit `5dbecd5`, not the later checkpoint/state-only HEAD, and their detailed reports were not branch-local.
+- Adversarial reviewer: OpenAI GPT-5.6-sol; implementer provider was not recorded, so cross-provider independence cannot be confirmed and evidence is weaker.
+- ADR governance review confirmed that the policy corrections belong in existing Proposed ADR-0016 and require no new ADR.
+- Adversarial remediation commit `fb67648` addresses the policy findings by adding stable/general-availability eligibility, symmetric security qualification, deterministic release discovery/ordering, continuing incumbent requalification, precise ADR-0003/0004/0006/0013/0014 supersession, pointer-compatible skill parity, and separate distributable/dependency identity contracts.
+- Independent code review at `e3df509` returned `issues_found`; the exact report is committed at `planning/adr-0016-code-review-e3df509.md`.
+  - HIGH: candidate selection is undefined if maximal eligible sets fail qualification while a dominated older set could pass.
+  - HIGH: continuing incumbent requalification omits provenance-integrity changes, mandatory-baseline changes, and newly discovered non-security runtime/capability evidence.
+  - MEDIUM: mutable installation aliases can move to an unqualified release after a point-in-time clean-install check.
+- Goal verification did not run because code review blocked advancement. Adversarial re-review, Craft, and fresh clean-context remain pending.
+- Lifecycle correction commit `9c2f1da` defines deterministic newest-first evaluation across all eligible sets, requalification on every qualification-input change, immutable default install selectors, and alias-target requalification. Local ADR governance, 20 governance tests, and `git diff --check` passed.
+- Independent code review at `2dd687b` resolved the two previous HIGH lifecycle findings and found two remaining issues; the exact report is `planning/adr-0016-code-review-2dd687b.md`.
+  - HIGH: skill pointers require fetched released docs but lack a durable untrusted-content/prompt-injection boundary.
+  - MEDIUM: mutable aliases are prohibited as default/recommended selectors but later language allows them to continue being recommended after requalification.
+- Goal verification did not run because code review blocked advancement.
+- Pointer-security correction commit `4873f36` makes fetched docs untrusted factual input that cannot override instructions or gates, and prohibits mutable aliases from ever being default, supported, or recommended install commands. Local ADR governance, 20 governance tests, and `git diff --check` passed.
+- Final independent code review at `481ca8c`: passed with no findings. The exact report is committed at `planning/adr-0016-code-review-481ca8c.md`.
+- Exact-HEAD goal verification at `9bd4f6f`: passed, 10/10 decision-contract goals verified with no gaps. The report is committed at `planning/adr-0016-verification-9bd4f6f.md`.
+- Exact-head adversarial re-review at `dfd14da`: `NOT-READY`. The report is committed at `planning/adr-0016-adversarial-dfd14da.md`.
+  - HIGH: the ADR simultaneously makes mandatory-baseline qualification global to one coherent release set and permits journey-local retention/withdrawal. One unit of qualification and fallback must be chosen.
+  - LOW: state/checkpoint must distinguish the historical branch point from the current PR base and describe scope-gated CI checks honestly.
+- Craft and clean-context did not run because adversarial blocked advancement.
+- Jim chose option 2 on 2026-08-20: one active coherent release set with journey-local support status, no mixed versions or per-journey old-release fallback, and global no-supported-baseline only when no eligible set supplies complete routes for every mandatory core outcome.
+- Journey-local amendment `fb00f10` formalizes that decision, including same-interface complete routes, global set selection/fallback, atomic optional-journey regression disclosure, journey-keyed manifest/docs/skill parity, and the minimum end-to-end store-and-retrieve outcome. Local ADR governance and 20 tests passed; exact-head draft-PR CI and GitBook checks are green.
+- Exact-head adversarial re-review remained pending after the journey-local amendment.
+- Exact-head code review at `b1e4846`: passed with no findings and all qualification truth-table scenarios passed. Report: `planning/adr-0016-code-review-b1e4846.md`.
+- Exact-head goal verification at `39e2cdf`: passed, 10/10 goals and all required truth-table scenarios verified with no gaps. Report: `planning/adr-0016-verification-39e2cdf.md`.
+- Exact-head adversarial re-review at `ef646b9`: `NOT-READY`. Report: `planning/adr-0016-adversarial-ef646b9.md`.
+  - HIGH: top-level `SDK` continuity still permits incompatible bindings/transports to be combined into a false complete route.
+  - HIGH: allowing CLI to become the only recommended complete route changes ADR-0011's unconditional SDK-primary stance, so ADR-0011 must be precisely superseded rather than called intact.
+  - MEDIUM: branch-local truth-table evidence must include concrete binding, transport, installation, runtime/configuration, and carried-state identities.
+  - LOW: state/checkpoint/PR evidence was stale, and the historical v0.11.2 defect sentence needs past-tense scoping.
+- Craft and clean-context did not run because adversarial blocked advancement.
+- Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used.
+  - `models: unavailable (auth) · 0s`
+- CI arbiter: draft PR #98. Exact reviewed head `ef646b9` passed ADR Governance and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage.
+- Freshness risk: the imported v0.11.2 audit is explicitly historical; `antd` v0.12.0 has since released and issue #233 has closed. A fresh candidate-release audit is required before implementation, regardless of ADR acceptance.
+
+## Constraints
+
+- Do not edit Accepted ADR-0003 or ADR-0004.
+- Do not mark ADR-0016 Accepted autonomously.
+- Do not implement manifest, tooling, policy, or rendered-documentation changes before the ADR decision gate.
+- Do not open a PR without Jim's explicit confirmation.
+
+## Next
+
+- With Jim's attended approval, add concrete complete-route continuity, precisely supersede ADR-0011's unconditional SDK-primary clause, scope the historical v0.11.2 sentence, and add inspectable concrete truth-table evidence; then rerun code review, verification, CI, and adversarial. Do not merge, accept the ADR, or begin implementation.

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