diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md new file mode 100644 index 0000000..ea1bea7 --- /dev/null +++ b/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. diff --git a/planning/STATE.md b/planning/STATE.md new file mode 100644 index 0000000..856c1c7 --- /dev/null +++ b/planning/STATE.md @@ -0,0 +1,139 @@ +# GSD State + +## Current Position + +- Phase: released-truth source-of-truth decision +- Plan: supersede ADR-0003 before documentation remediation +- Task: reconcile final acceptance-record evidence after exact-head adversarial review +- Status: ADR-0016 is Accepted by Jim; merge authorization is settled; implementation remains unauthorized; final adversarial rerun, Craft Review, any needed focused consistency check, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head remain as mechanical merge conditions +- Mode: attended +- Branch: `adr/released-and-usable-truth` +- PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) +- Branch point: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` +- Current PR base: `origin/main` at `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; tightening `f326e0c3f65de0646495da02d6eb74b70dac966f`; evidence-alignment correction `dfe2161` +- Implementation: not started or authorized; it requires a separate approved spec, plan, and slice plus a fresh release audit +- Human decision supplied in chat on 2026-08-31: Jim is happy to accept ADR-0016 via PR #98 and authorizes it to be accepted and merged. Writing `Accepted` records and implements Jim's decision; it is not autonomous AI acceptance. + +## Decision Intent + +- Public documentation describes stable or general-availability software available through supported public routes. +- An explicit release baseline provides exact provenance for released components, shipped dependencies, and relevant deployed-network behavior. +- Unreleased source may prepare future documentation but cannot support default public claims. +- Known defects and unsupported tasks are represented honestly; pre-release documentation remains separate. +- A separate developer skill is outside this decision. + +## 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; PR CI and GitBook checks were green for that revision. +- 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. +- Jim then directed a scope reset: ADR-0016 should state only the durable rule that public documentation covers stable software the public can obtain. Skill ownership, journey models, route truth tables, comparison algorithms, and implementation mechanics moved out of the ADR. +- Concise content commit `afdaa07` replaced the detailed proposal; `f326e0c` tightened it to 477 words including metadata and headings. It now supersedes only the public source-selection/provenance clauses in ADR-0003, ADR-0004, and ADR-0006 and explicitly leaves any separate developer skill out of scope. +- ADR Governance, 20 local governance tests, diff check, and PR CI passed for `f326e0c`. The earlier route-continuity and ADR-0011 findings applied to removed decisions and require fresh review rather than mechanical remediation. +- Fresh code review at `752099a`: passed with no findings. The 477-word ADR, template, American English, partial supersession, target-architecture scope, Accepted-ADR immutability, and exact-head CI all passed. Report: `planning/adr-0016-code-review-752099a.md`. +- Goal verification at `85fde83`: ADR content passed all 11 applicable decision goals; the twelfth state/PR accuracy goal found two bookkeeping gaps. Report: `planning/adr-0016-verification-85fde83.md`. + - `STATE.md` still described removed skill/mode intent. + - PR #98 still called the completed fresh code review pending. +- Reverification at `d09520e`: ADR content and the first bookkeeping corrections passed; two further checkpoint accuracy gaps and the invalid recorded `f326e0c` full SHA remained. These are corrected in the current state/checkpoint update. +- Final exact-head reverification at `58545cd`: passed 12/12 with no gaps. Report: `planning/adr-0016-verification-58545cd.md`. +- Fresh adversarial review at `d18a63b`: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. Report: `planning/adr-0016-adversarial-d18a63b.md`. + - LOW: validation wording should preserve the deployed-network evidence path. Corrected in `dfe2161`. + - LOW: PR body lagged final verification. Corrected after review. +- Focused code review at `fc49173`: ADR content passed with no findings; one MEDIUM checkpoint-consistency issue remained. Report: `planning/adr-0016-code-review-fc49173.md`. + - The accumulated checkpoint mixed current READY-WITH-NITS status with historical blocker/pending language. It is replaced by a concise current checkpoint; detailed history remains in the review reports. +- Exact-head focused checkpoint review at `dcf7c8c`: passed with no findings. +- Craft Review at `dcf7c8c`: passed with no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-craft-dcf7c8c.md`. +- Clean-context review at `dcf7c8c`: blocked before inference because the controlled Claude panel lacks the separate Milestone A activation verdict. No substitute was used. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. +- Jim chose `Stop pending activation` on 2026-08-28. Clean-context is not waived, panel activation is not authorized by this ADR, and the acceptance checkpoint remains blocked. +- Jim subsequently declared: `Milestone A panel activation approved for normal and ad-hoc controlled external reviews.` on 2026-08-28. This activates the controlled panel beyond PR #98; it does not authorize ADR acceptance, merge, or implementation. +- Activated dispatch attempt for evidence revision `50f4462` was blocked before inference because the required caller-owned disposable root and `brief.md` could not be created under the orchestrator's outer filesystem permission. No model ran. Report: `planning/adr-0016-clean-context-50f4462.md`. + - `models: provider=not-observed · model=not-resolved · duration=unknown` + - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` +- Jim explicitly authorized creation of disposable root `gsd-panel-a1ae9d0a-d513-47f5-8266-b006db956517` and a credential-free brief of at most 16 KiB for revision `0df9bfd`. The outer harness still denied the exact `mkdir` call because its final static external-directory deny overrides the authorization. This is now a mechanism-level blocker; no model ran. +- Jim's `waive and present` declaration was recorded in commit `f3f3bdc735d5357ea4a03741163a800510a8b61c` on 2026-08-29. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. +- Clean-context controlling disposition: Jim's one-off waiver follows the blocked-before-inference controlled-panel sequence above; no same-model substitute ran. +- CI arbiter: process-required ADR Governance and the GitHub branch-protection-required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: + - Process-required ADR Governance run `33245584910`, job `99082354387`, passed substantively; checkout, regression tests, and governance checks ran successfully. + - GitHub branch-protection-required prose run `33245584905`, job `99082354434`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main prose validation were skipped. + - GitHub branch-protection-required sweep run `33245584892`, job `99082354463`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main metadata-envelope validation were skipped. + - GitHub branch-protection-required sweep SHA reachability run `33245584906`, job `99082354330`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. + - GitBook status `GitBook`: passed. + - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. +- These results are historical pre-remediation evidence. Subsequent remediation commits therefore required fresh process-required ADR Governance and GitHub branch-protection-required checks. +- Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. Commit `6e9f056` removed those commands; re-review and fresh process-required ADR Governance plus GitHub branch-protection-required checks were pending at that point and are completed below. +- Re-review of `6e9f056` found a MEDIUM CI-scope record issue and a LOW clean-context waiver-date record issue. Commit `1091016` records the three scope-gated jobs as successful no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; final review and CI evidence follow below. +- Final code review of remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` against base `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: passed with no findings. Report: `planning/adr-0016-evidence-remediation-code-review-1091016.md`. +- Independent verification of the same range: passed 10/10 goals. It confirmed all 31 ant-sdk refs use exact 40-character SHAs, representative URLs return HTTP 200, local-only docs commits remain unavailable and unlinked, no unreachable compare command remains, PR/base/merge and CI-scope records are accurate, Craft and waiver records are coherent, no readiness is overclaimed, the ADR tree is unchanged, and only the three in-scope planning files changed. ADR governance passed with 1 ADR checked, all 20 governance tests passed, and the diff check passed. Report: `planning/adr-0016-evidence-remediation-verification-1091016.md`. +- CI associated with reviewed remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` is green. Process-required ADR Governance run `33376786646`, job `99439965340`, was associated with that PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran. GitHub branch-protection-required prose run `33376786657` / job `99439965599`, sweep run `33376786692` / job `99439965589`, and sweep SHA reachability run `33376786655` / job `99439965598` were successful `not applicable` scope-gate no-ops with main validation skipped. Both GitBook statuses passed. +- Adversarial review of the remediation range: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. LOW: living records lagged completed review and CI; the PR body claimed the ADR was ready but repeatedly used stale `draft` language while live PR #98 was open and non-draft. NIT: `exact-head CI` wording needed to disclose execution on a clean synthetic merge ref. This record update resolves the living-status and CI-wording findings; the orchestrator will remove the stale `draft` wording from the PR body after final CI. Model-diversity evidence is weaker because the reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass, and the implementer provider is unrecorded. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. +- Fresh-context Craft Review of the remediation range: PASS with no CONFORMANCE, SIMPLICITY, or NIT findings. It used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. +- Acceptance-record code review of `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`: passed with no findings. ADR governance passed with 1 ADR checked, all 20 governance tests passed, and diff/protected-scope checks passed. Only the three expected files changed. ADR-0016 changed only Status, Acceptance, and the final note; its decision remained unchanged at 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. Report: `planning/adr-0016-acceptance-code-review-e2d54b2.md`. +- Independent acceptance-record verification of the same range: passed 7/7. Jim, PR #98, and 2026-08-31 form the recorded human-acceptance basis; ADR-0015 permits the introducing-PR transition and places immutability at the default branch; only authorized scopes changed; governance, tests, and diff checks passed. At review time the remote still needed the acceptance commits; that condition has since been satisfied and CI associated with `e2d54b26e5d510419885345e22a2374d46aeb710` is green. Report: `planning/adr-0016-acceptance-verification-e2d54b2.md`. +- CI associated with accepted head `e2d54b26e5d510419885345e22a2374d46aeb710` is green: + - 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. ADR Governance is process-required but is not GitHub branch-protection-required. + - 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. +- Exact-head adversarial review at `e2d54b26e5d510419885345e22a2374d46aeb710`: `NOT-READY`. Report: `planning/adr-0016-acceptance-adversarial-e2d54b2.md`. + - HIGH: the live PR body contradicted acceptance and merge authorization and had stale head, count, and merge-ref evidence. The orchestrator corrected the live PR body before this reconciliation commit. + - MEDIUM: state and checkpoint still marked completed code review, verification, and CI pending and lacked branch-local code-review and 7/7 verification reports. This reconciliation commit updates the records and adds both reports. + - LOW: 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 `not applicable` no-ops here. This reconciliation commit uses explicit wording. + - No content or governance failure was found: the ADR decision remained unchanged at 497 words, local checks passed, and ADR-0015 alignment was correct. + - The reviewer was OpenAI GPT-5.6-sol, the same provider/model as the earlier review. The implementer provider is unrecorded, so independence evidence is weaker. +- Prior proposal Craft Review passed. Acceptance-record Craft Review has not run because the exact-head adversarial review blocked it. Final adversarial rerun and Craft Review are mandatory merge conditions after this reconciliation commit. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. +- Remaining merge conditions are a final adversarial rerun, Craft Review, a focused consistency check as needed, and green process-required ADR Governance plus GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final head. These are mechanical conditions, not owner decisions. +- 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. +- The `Accepted` status implements Jim's explicit 2026-08-31 decision; it is not autonomous AI acceptance. +- Do not implement manifest, tooling, policy, or rendered-documentation changes without a separate approved spec, plan, and slice plus a fresh release audit. +- Jim authorized merge of PR #98 on 2026-08-31, conditional on final mechanical review and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head. + +## Next + +- Run the final adversarial rerun, Craft Review, and a focused consistency check as needed. +- Confirm process-required ADR Governance and GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final PR head are green, then merge PR #98 under Jim's authorization. +- Do not begin implementation. After merge, ADR-0016 is immutable; later changes require a superseding ADR. diff --git a/planning/adr-0016-acceptance-adversarial-e2d54b2.md b/planning/adr-0016-acceptance-adversarial-e2d54b2.md new file mode 100644 index 0000000..f40cd5b --- /dev/null +++ b/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. diff --git a/planning/adr-0016-acceptance-code-review-e2d54b2.md b/planning/adr-0016-acceptance-code-review-e2d54b2.md new file mode 100644 index 0000000..8176dd7 --- /dev/null +++ b/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. diff --git a/planning/adr-0016-acceptance-verification-e2d54b2.md b/planning/adr-0016-acceptance-verification-e2d54b2.md new file mode 100644 index 0000000..56e747a --- /dev/null +++ b/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. diff --git a/planning/adr-0016-adversarial-d18a63b.md b/planning/adr-0016-adversarial-d18a63b.md new file mode 100644 index 0000000..2bdedff --- /dev/null +++ b/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. diff --git a/planning/adr-0016-adversarial-dfd14da.md b/planning/adr-0016-adversarial-dfd14da.md new file mode 100644 index 0000000..3e3ee04 --- /dev/null +++ b/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. diff --git a/planning/adr-0016-adversarial-ef646b9.md b/planning/adr-0016-adversarial-ef646b9.md new file mode 100644 index 0000000..18af5de --- /dev/null +++ b/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. diff --git a/planning/adr-0016-clean-context-50f4462.md b/planning/adr-0016-clean-context-50f4462.md new file mode 100644 index 0000000..326dccb --- /dev/null +++ b/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-` 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 diff --git a/planning/adr-0016-clean-context-dcf7c8c.md b/planning/adr-0016-clean-context-dcf7c8c.md new file mode 100644 index 0000000..f564873 --- /dev/null +++ b/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` diff --git a/planning/adr-0016-code-review-2dd687b.md b/planning/adr-0016-code-review-2dd687b.md new file mode 100644 index 0000000..f526cb4 --- /dev/null +++ b/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. diff --git a/planning/adr-0016-code-review-481ca8c.md b/planning/adr-0016-code-review-481ca8c.md new file mode 100644 index 0000000..3231f71 --- /dev/null +++ b/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. diff --git a/planning/adr-0016-code-review-752099a.md b/planning/adr-0016-code-review-752099a.md new file mode 100644 index 0000000..2e48711 --- /dev/null +++ b/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. diff --git a/planning/adr-0016-code-review-b1e4846.md b/planning/adr-0016-code-review-b1e4846.md new file mode 100644 index 0000000..07ef3a1 --- /dev/null +++ b/planning/adr-0016-code-review-b1e4846.md @@ -0,0 +1,38 @@ +# ADR-0016 code review — b1e4846 + +- Date: 2026-08-20 +- Reviewed commit: `b1e48469dc96928beb4ef6d9e04dd3a0acc04e9c` +- Current PR base: `487866a249fcb5ad7d8dd7829c017ed63d421343` +- 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. +- PR #98 mergeability and base/head confirmed. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful branch-scope no-ops. +- Full PR diff and content commit `fb00f10` inspected. +- Accepted ADR-0003 through ADR-0007 and ADR-0011 through ADR-0015: byte-identical to current `origin/main`. +- ADR-0016 remained Proposed; no implementation or mechanism changes. + +## Findings + +None. + +The prior global-versus-journey qualification ambiguity is resolved by one default-public manifest, one coherent active set or global no-supported-baseline, journey-local statuses, complete same-interface routes, and global set fallback. + +## Truth-table result + +All reviewed scenarios passed: one/no active set, prohibited mixed versions and per-journey fallback, local SDK failure with surviving CLI route, rejected cross-interface patchwork, final-route loss and global fallback, atomic optional-journey downgrade, artifact-wide disqualification, bounded limitations, target-preview isolation, and untrusted pointer content. + +## Remaining risks + +- ADR-0016 still requires explicit human acceptance. +- Current docs and skill remain pre-implementation. +- Detailed schemas, route inventory, comparator, publication, migration, and enforcement remain specification/plan work. +- A fresh release audit is required before implementation. +- Exact-head goal verification, adversarial, Craft, and clean-context remain pending. +- Review lanes use the same model/provider; cross-model independence is weaker. diff --git a/planning/adr-0016-code-review-e3df509.md b/planning/adr-0016-code-review-e3df509.md new file mode 100644 index 0000000..82d54a4 --- /dev/null +++ b/planning/adr-0016-code-review-e3df509.md @@ -0,0 +1,52 @@ +# ADR-0016 code review — e3df509 + +- Date: 2026-08-20 +- Reviewed commit: `e3df50957d2691b8661c503bfd6f34cc960aece9` +- 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: four added files, 627 insertions. +- Content commit `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`: 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. The pull-request-triggered arbiter exists; local results are not CI-green. +- Worktree: clean at review time. + +## Findings + +### HIGH — Candidate selection after qualification failure is undefined + +Anchors: `adr/ADR-0016-released-truth-for-public-developer-docs.md:43,65-71,83-85` at the reviewed commit. + +The ADR promises the newest release set that passes, but computes maximal sets from eligibility before qualification. If every maximal eligible set fails while a dominated older set would pass, it does not say whether to evaluate that set, retain an incumbent, or declare no baseline. Different conforming specifications could produce different outcomes. + +Required disposition: define selection over qualified sets, deterministic iterative fallback through eligible sets, or an explicit no-fallback invariant. + +### HIGH — Continuing incumbent requalification omits qualification-changing events + +Anchors: `ADR-0016:67,83-85,158-168` at the reviewed commit. + +Outside promotion decisions, requalification is triggered only by artifact availability, safety/security evidence, and deployed-network changes. It omits provenance-integrity changes, mandatory-baseline changes, and newly discovered non-security runtime or capability defects. An incumbent could remain supported after a mandatory journey is proven broken when no new candidate exists. + +Required disposition: trigger requalification whenever any qualification input changes. + +### MEDIUM — Mutable installation aliases can bypass immutable released identity + +Anchors: `ADR-0016:57,67,78` at the reviewed commit. + +Mutable aliases are rejected only when they lack an immutable underlying identity. A point-in-time clean-install check could approve a documented `latest`-style route that later resolves to an unqualified release without triggering incumbent requalification. + +Required disposition: require default installation routes to pin immutable versions or digests, or make alias-target movement a mandatory requalification event. + +## Remaining risks + +- Applicable CI has not run and requires an authorized pull request. +- Goal verification, adversarial re-review, Craft, and clean-context remain outstanding after remediation. +- The v0.11.2 audit is historical; a fresh candidate audit is required before implementation. +- Implementer provider is unrecorded, so cross-provider independence cannot be confirmed. diff --git a/planning/adr-0016-code-review-fc49173.md b/planning/adr-0016-code-review-fc49173.md new file mode 100644 index 0000000..50e28ae --- /dev/null +++ b/planning/adr-0016-code-review-fc49173.md @@ -0,0 +1,34 @@ +# ADR-0016 code review — fc49173 + +- Date: 2026-08-28 +- Reviewed commit: `fc49173dc040425429a4cc298eb3811a23650b5a` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `issues_found` + +## ADR result + +The ADR passed with no findings. Its evidence-validation wording matched the Decision, the document remained durable and template-conformant at 481 words, and its partial supersession remained correct. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Diff check: passed. +- Worktree and remote head: clean and aligned at review time. +- Accepted ADRs: unchanged. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. + +## MEDIUM finding + +The checkpoint's summary recorded adversarial `READY-WITH-NITS`, but its historical detail still said `Blockers` and that adversarial review was pending. It also attributed pending Craft and clean-context to an old blocker rather than listing them as the next gates. + +Required disposition: replace the accumulated checkpoint with a concise current checkpoint and leave detailed history in the committed review reports. + +## Remaining risks + +- Craft and clean-context remain pending. +- Same-model review provides weaker independence. +- ADR acceptance remains human-only. +- A fresh release audit and reviewed specification are required before implementation. diff --git a/planning/adr-0016-craft-dcf7c8c.md b/planning/adr-0016-craft-dcf7c8c.md new file mode 100644 index 0000000..f480423 --- /dev/null +++ b/planning/adr-0016-craft-dcf7c8c.md @@ -0,0 +1,19 @@ +# ADR-0016 Craft Review — dcf7c8c + +- Date: 2026-08-28 +- Reviewed commit: `dcf7c8c5ca5199f174b5d493c3a75215933e3f4b` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: Craft — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `Pass` + +## Findings + +- CONFORMANCE: none. +- SIMPLICITY: none. +- NIT: none. + +ADR-0016 followed the repository template and governance, kept partial supersession precise, used American English, and remained concise. The larger branch footprint was attributable to historical audit and review evidence rather than speculative architecture or implementation. + +## Independence + +Fresh context, but the same model/provider as prior lanes. The implementer provider is unrecorded, so independence evidence is weaker. diff --git a/planning/adr-0016-evidence-remediation-adversarial-1091016.md b/planning/adr-0016-evidence-remediation-adversarial-1091016.md new file mode 100644 index 0000000..519f531 --- /dev/null +++ b/planning/adr-0016-evidence-remediation-adversarial-1091016.md @@ -0,0 +1,35 @@ +# ADR-0016 evidence-remediation adversarial review — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `READY-WITH-NITS` + +## Scope + +Adversarial review of the planning-only evidence-remediation range and its readiness record for the Proposed ADR-0016 acceptance decision. + +## Findings + +No CRITICAL, HIGH, or MEDIUM findings. + +### LOW — Living status lagged readiness + +`planning/STATE.md` and `planning/gsd-adr-0016-checkpoint.md` still described review and CI as pending. The PR body claimed the ADR was ready but repeatedly used stale `draft` language, while live PR #98 was open and non-draft. + +Disposition: the final branch-local record update resolves the living-status and CI-wording findings. The orchestrator will remove the stale `draft` wording from the PR body after final CI. + +### NIT — CI execution ref needed explicit wording + +The phrase `exact-head CI` did not disclose that GitHub associated ADR Governance with the PR head but executed it on a clean synthetic PR merge ref. + +Disposition: the final state and checkpoint distinguish head association from execution on the synthetic merge ref. + +## Decision boundary + +ADR-0016 can be presented for human acceptance after the current-head conditions pass. This review does not authorize acceptance, merge, implementation, or publication. + +## Independence + +Model-diversity evidence is weaker: this review used OpenAI GPT-5.6-sol, the same model as the earlier pass. The implementer provider is unrecorded, so cross-provider independence cannot be confirmed. diff --git a/planning/adr-0016-evidence-remediation-code-review-1091016.md b/planning/adr-0016-evidence-remediation-code-review-1091016.md new file mode 100644 index 0000000..266fdb5 --- /dev/null +++ b/planning/adr-0016-evidence-remediation-code-review-1091016.md @@ -0,0 +1,14 @@ +# ADR-0016 evidence-remediation code review — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Result: `passed` + +## Scope + +Final code review of the planning-only evidence-remediation range between the reviewed base and head. + +## Findings + +None. No additional code-review detail was recorded. diff --git a/planning/adr-0016-evidence-remediation-craft-1091016.md b/planning/adr-0016-evidence-remediation-craft-1091016.md new file mode 100644 index 0000000..e871953 --- /dev/null +++ b/planning/adr-0016-evidence-remediation-craft-1091016.md @@ -0,0 +1,21 @@ +# ADR-0016 evidence-remediation Craft Review — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Reviewer: Craft — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `PASS` + +## Scope + +Fresh-context Craft Review of the planning-only evidence-remediation range. + +## Findings + +- CONFORMANCE: none. +- SIMPLICITY: none. +- NIT: none. + +## Independence + +The review used fresh context but the same OpenAI GPT-5.6-sol model and provider as the earlier pass. The implementer provider is unrecorded, so independence evidence is weaker. diff --git a/planning/adr-0016-evidence-remediation-verification-1091016.md b/planning/adr-0016-evidence-remediation-verification-1091016.md new file mode 100644 index 0000000..3846ebb --- /dev/null +++ b/planning/adr-0016-evidence-remediation-verification-1091016.md @@ -0,0 +1,26 @@ +# ADR-0016 evidence-remediation verification — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Reviewer: verifier +- Result: `passed` +- Score: 10/10 goals verified + +## Scope + +Independent verification of the planning-only evidence remediation in `planning/STATE.md`, `planning/gsd-adr-0016-checkpoint.md`, and `planning/released-antd-v0.11.2-audit.md`. + +## Evidence + +- All 31 ant-sdk source references use exact 40-character commit SHAs; representative blob URLs returned HTTP 200. +- Local-only documentation commits remain unavailable remotely and are not linked. +- No unreachable compare command remains. +- PR, base, merge, CI-scope, Craft Review, and clean-context-waiver records are accurate and coherent. +- The records make no readiness overclaim. +- The ADR tree is unchanged, and only the three in-scope planning files changed in the reviewed range. +- ADR governance passed with 1 ADR checked; all 20 governance tests passed; the diff check passed. + +## Findings + +None. diff --git a/planning/adr-0016-verification-39e2cdf.md b/planning/adr-0016-verification-39e2cdf.md new file mode 100644 index 0000000..6b5c3a7 --- /dev/null +++ b/planning/adr-0016-verification-39e2cdf.md @@ -0,0 +1,51 @@ +# ADR-0016 goal verification — 39e2cdf + +- Date: 2026-08-20 +- Reviewed commit: `39e2cdff010a5ef729f2d655b29ef684a3c0118f` +- Current PR base: `487866a249fcb5ad7d8dd7829c017ed63d421343` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `passed` +- Score: 10/10 decision-contract goals verified + +The previous global-versus-journey ambiguity is resolved. The contract has one global release-set incumbent, journey-local statuses within that set, same-interface complete routes, and global-only release-set fallback. + +## Verified goals + +1. Exactly one manifest and active coherent set, or global `no-supported-baseline`; no mixed versions or per-journey release fallback. +2. Stable/general-availability released truth with immutable identities, coherent dependencies/network state, and no moving-source or preview fallback. +3. Journey statuses are derived separately before global release-set qualification. +4. Every mandatory outcome has a predeclared complete same-interface route; minimum store-and-retrieve passes end to end. +5. Isolated journey failures preserve unaffected journeys; artifact-wide issues and final-route loss fail global qualification. +6. Deterministic global selection and fallback remain complete; optional regressions require atomic cross-surface downgrade. +7. Journey evidence, status, limitations, alternatives, recommendations, docs, skill pointers, and fetched-content security align. +8. Partial supersession, ADR-0011 relationship, Accepted-ADR immutability, and ADR/spec boundaries are correct. +9. Historical audit, fresh-audit requirement, CI coverage, and scope-gated no-ops are recorded honestly. +10. ADR-0016 remains Proposed; no implementation, merge, or acceptance is claimed. + +## Truth-table result + +All required scenarios passed: SDK failure with a surviving CLI complete route, rejected cross-interface patchwork, isolated MCP failure, atomic optional regression, artifact-wide issue, uncertain scope, global older-set fallback, global no-supported-baseline, no old-set journey fallback, and bounded limitation. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- `git diff --check 487866a...39e2cdf`: passed. +- Worktree: clean at review time. +- Accepted ADRs: byte-identical to the current PR base; only Proposed ADR-0016 differs under `adr/`. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. +- Draft PR #98 remained open, draft, mergeable, and behind base. + +## Gaps + +None at the Proposed ADR decision-contract level. + +## Remaining risks + +- ADR-0016 requires explicit human acceptance. +- Adversarial re-review, Craft, and clean-context remain pending. +- Review lanes use the same model/provider; independence is weaker. +- A fresh release audit is required before implementation. +- Detailed schemas, route inventory, comparator, publication, migration, and enforcement remain specification/plan work. +- Current docs and skill remain pre-implementation. diff --git a/planning/adr-0016-verification-58545cd.md b/planning/adr-0016-verification-58545cd.md new file mode 100644 index 0000000..a9975b1 --- /dev/null +++ b/planning/adr-0016-verification-58545cd.md @@ -0,0 +1,42 @@ +# ADR-0016 goal verification — 58545cd + +- Date: 2026-08-28 +- Reviewed commit: `58545cd04936d1c13c44d27d80acf94cec6cb8e9` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `passed` +- Score: 12/12 goals verified + +## Verified + +- All concise ADR decision goals passed. +- ADR-0016 remained unchanged from tightening commit `f326e0c3f65de0646495da02d6eb74b70dac966f` and contained 477 words including metadata and headings. +- All prior bookkeeping gaps were corrected. +- State, checkpoint, ADR, and PR body agreed on the concise scope. +- No current skill, journey, route, or comparison architecture remained. +- Partial supersession of ADR-0003, ADR-0004, and ADR-0006 was limited appropriately. +- All Accepted ADRs were byte-identical to the current base. +- ADR-0016 remained Proposed; no implementation or rendered-doc change was included. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Diff check: passed. +- Worktree and remote head: clean and aligned at review time. +- PR #98: open, draft, exact head, and mergeable. +- Exact-head ADR Governance run `33202671819`, job `98955766230`: passed. +- Both GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. + +## Gaps + +None. + +## Remaining risks + +- Adversarial, Craft, and clean-context remain pending. +- ADR acceptance requires Jim's human decision. +- A fresh release audit is required before implementation. +- Same-model verification provides weaker independence. +- The branch is behind current base; any content-changing integration requires renewed review. diff --git a/planning/adr-0016-verification-85fde83.md b/planning/adr-0016-verification-85fde83.md new file mode 100644 index 0000000..fb9cb31 --- /dev/null +++ b/planning/adr-0016-verification-85fde83.md @@ -0,0 +1,37 @@ +# ADR-0016 goal verification — 85fde83 + +- Date: 2026-08-28 +- Reviewed commit: `85fde835e16d1891162c86abfed373e5bc36ec2a` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `gaps_found` +- Score: 11/12 goals verified + +## Verified + +The concise ADR passed all decision-content goals: obtainable stable releases, explicit baseline, coherent multi-component provenance, reviewed promotion, honest defects, separated previews, skill exclusion, deferred implementation, precise partial supersession, Proposed status, template conformance, and the 477-word cap. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Word count: 477 including metadata and headings. +- Diff check: passed. +- Accepted ADRs: byte-identical to the current base. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. +- Worktree and remote head: clean and aligned at review time. + +## Gaps + +- `planning/STATE.md` still described skill inclusion and detailed verification-mode machinery as current intent despite the later scope reset. +- PR #98 still said fresh code review was pending after it had passed. + +These are state and PR-body accuracy gaps, not ADR-content gaps. + +## Remaining risks + +- ADR-0016 remains Proposed and requires human acceptance. +- Adversarial, Craft, and clean-context remain pending. +- A fresh release audit is required before implementation. +- Same-model verification provides weaker independence. diff --git a/planning/adr-0016-verification-9bd4f6f.md b/planning/adr-0016-verification-9bd4f6f.md new file mode 100644 index 0000000..d334d5d --- /dev/null +++ b/planning/adr-0016-verification-9bd4f6f.md @@ -0,0 +1,47 @@ +# ADR-0016 goal verification — 9bd4f6f + +- Date: 2026-08-20 +- Reviewed commit: `9bd4f6f0780d3a431a134214f9abaa3fddb45ea4` +- Base: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `passed` +- Score: 10/10 decision-contract goals verified +- Evidence strength: local validation passed; applicable CI has not run + +This verification applies at the decision-contract level. It does not claim that the existing docs and skill implement ADR-0016. + +## Verified goals + +1. Released, obtainable, coherent, capability-evidenced truth is the public default. +2. Defects, alternatives, unsupported states, and no-supported-baseline behavior are honest and fail closed. +3. Candidate/incumbent qualification and deterministic fallback are symmetric and complete. +4. Default, supported, and recommended installation routes use immutable identities. +5. Default branches, target previews, and retired `current-merged-truth` are separated. +6. Partial supersession of ADR-0003, ADR-0004, ADR-0006, ADR-0013, and ADR-0014 is precise; Accepted files remain immutable. +7. Skill pointer parity preserves ADR-0013 and treats fetched material as untrusted factual input. +8. Public distributable and transitive dependency identities are distinct. +9. ADR/spec/plan boundaries remain clean; ADR-0016 remains Proposed and implementation is unauthorized. +10. Audit, state, checkpoint, CI, and freshness limitations are recorded honestly. + +## Checks + +- Worktree and base confirmed; worktree clean. +- Complete base diff inspected: seven added files, 812 insertions at review time. +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- `git diff --check af6d0e9..9bd4f6f`: passed. +- Accepted ADRs: byte-identical to base. +- Applicable CI workflow exists, but no exact-SHA run or remote branch exists; evidence is not CI-green. + +## Gaps + +None at the decision-contract level. + +## Remaining decisions and risks + +- ADR-0016 requires explicit human acceptance. +- Adversarial re-review, Craft, and clean-context remain outstanding. +- Pull-request-triggered CI requires authorization for the exact PR action. +- A fresh v0.12.0 candidate audit is required before implementation. +- Existing docs and skill remain pre-implementation and do not yet enforce the proposal. +- Manifest, comparator, watch-state, baseline, migration, and enforcement details require a reviewed specification and plan. diff --git a/planning/adr-0016-verification-d09520e.md b/planning/adr-0016-verification-d09520e.md new file mode 100644 index 0000000..32f78da --- /dev/null +++ b/planning/adr-0016-verification-d09520e.md @@ -0,0 +1,42 @@ +# ADR-0016 goal verification — d09520e + +- Date: 2026-08-28 +- Reviewed commit: `d09520e6f766a7ca51f0d735165aebd0410f229e` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `gaps_found` +- Score: 11/12 goals verified + +## Verified + +- All concise ADR-content goals passed. +- State Decision Intent matched the scope reset. +- PR #98 accurately reported the concise decision, 477-word count, completed code review, historical audit, scope-gated checks, and pending gates. +- Removed journey, skill-architecture, route, and comparison decisions were not presented as current ADR content. +- Accepted ADRs remained byte-identical to the current base. +- Exact-head ADR Governance and GitBook checks passed. + +## Gaps + +- `planning/STATE.md` recorded an invalid full SHA for tightening commit `f326e0c`. +- The checkpoint called an older review the latest passing review, retained a completed PR-body correction as its next step, and did not record the exact `d09520e` CI run. + +These were bookkeeping/evidence-accuracy gaps, not ADR-content defects. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Word count: 477. +- Diff check: passed. +- Worktree and remote head: clean and aligned at review time. +- Exact-head ADR Governance run `33189218449`, job `98910092392`: passed. +- Both GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. + +## Remaining risks + +- ADR-0016 remains Proposed and requires human acceptance. +- Adversarial, Craft, and clean-context remain pending. +- A fresh release audit is required before implementation. +- Same-model verification provides weaker independence. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md new file mode 100644 index 0000000..fe1ee7a --- /dev/null +++ b/planning/gsd-adr-0016-checkpoint.md @@ -0,0 +1,143 @@ +# GSD Checkpoint — Accepted ADR-0016 + +Date: 2026-08-31 +Project: Autonomi Developer Documentation +Slice/question: Should public documentation describe only stable software the public can obtain? +Prepared by: orchestrator +Agents/tools used: operative, codereviewer, verifier, adversarial; prior proposal Craft passed; acceptance-record Craft not yet run; clean-context Jim-waived for ADR-0016 + +## Status + +Continue — ADR-0016 is Accepted by Jim and merge authorization is settled. Complete the final adversarial rerun, Craft Review, any needed focused consistency check, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head as mechanical gates, then merge PR #98 under Jim's 2026-08-31 authorization. Implementation remains unauthorized. + +Meaningful work-unit? Yes — the decision changes the durable public source-of-truth policy. +Review cadence: acceptance-record code review and verification completed; exact-head adversarial review returned `NOT-READY`; rerun adversarial and Craft Review after this remediation +Unreviewed backlog: final adversarial rerun, acceptance-record Craft Review, focused consistency check as needed, and CI on the resulting final head; clean-context remains explicitly Jim-waived for ADR-0016 + +## What happened + +Jim replaced the detailed proposal with a concise target decision: public documentation describes stable or general-availability software available through supported public routes. An explicit release baseline provides exact provenance; unreleased source cannot support default public claims; defects and unsupported tasks are represented honestly. + +The ADR is 497 words including metadata and headings. Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside its scope. It partially supersedes only ADR-0003, ADR-0004, and ADR-0006. + +Jim's explicit human decision, supplied in chat on 2026-08-31, is to accept ADR-0016 via PR #98 and authorize it to be accepted and merged. Writing `Accepted` implements Jim's decision; it is not autonomous AI acceptance. + +No implementation, rendered docs, skill, CI, test, harness, or other ADR changed. Implementation remains unauthorized without a separate approved spec, plan, and slice plus a fresh release audit. The introducing PR remains reviewable until merge; after ADR-0016 lands on the default branch, it is immutable and later changes require a superseding ADR. + +## Evidence + +CI arbiter / green of record: + +- Location: PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) +- Rule: process-required ADR Governance and GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final PR head are the green of record. ADR Governance is process-required but is not GitHub branch-protection-required. +- Reviewed acceptance head: `e2d54b26e5d510419885345e22a2374d46aeb710`. +- Process-required ADR Governance run `33392124485`, job `99487983002`: associated with head `e2d54b2` and executed on clean synthetic merge ref `c53dfc6d1b422099ed5dadb2406f0d8876409920`; checkout, all 20 tests, and governance passed. +- GitHub branch-protection-required prose run `33392124442`, job `99487983034`: green `not applicable` scope-gate no-op; main validation was skipped. +- GitHub branch-protection-required sweep run `33392124448`, job `99487983102`: green `not applicable` scope-gate no-op; main validation was skipped. +- GitHub branch-protection-required sweep SHA reachability run `33392124434`, job `99487982641`: green `not applicable` scope-gate no-op; main validation was skipped. +- GitBook status `GitBook`: passed. +- GitBook status `GitBook - docs.autonomi.com/developers/`: passed. +- The resulting final head after this reconciliation must receive green process-required ADR Governance and GitHub branch-protection-required checks before merge. + +Local fast gate / `.gsd/gate.sh`: + +- Installed? N/A — no `.gsd/gate.sh` exists. +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20/20 tests. +- ant-sdk blob ref length check: passed, 31 refs checked and all are 40 characters. +- `git diff --check`: passed. +- Word count: 497. + +Artifacts: + +- `adr/ADR-0016-released-truth-for-public-developer-docs.md` +- `planning/released-antd-v0.11.2-audit.md` +- `planning/STATE.md` +- This checkpoint +- `planning/adr-0016-acceptance-code-review-e2d54b2.md` +- `planning/adr-0016-acceptance-verification-e2d54b2.md` +- `planning/adr-0016-acceptance-adversarial-e2d54b2.md` +- Exact-SHA reports matching `planning/adr-0016-*.md` + +## Honesty Rules + +- No-harness-modification: Pass. No gate, CI, test, build, or environment change. +- Baseline-diff for evidence: Pass. No failure was dismissed. +- Evidence reproducible-from-branch: Pass. +- Local vs CI consistency: Pass at reviewed head `e2d54b2`. Merge remains conditioned on green process-required ADR Governance and GitHub branch-protection-required checks on the resulting final head. + +## Review Findings + +Code review: + +- Acceptance-record review range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`. +- Result: `passed` with no findings. +- ADR governance passed with 1 ADR checked; all 20 governance tests passed; diff and protected-scope checks passed. +- Only the three expected files changed. +- ADR-0016 changed only Status, Acceptance, and the final note. Its 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. +- Report: `planning/adr-0016-acceptance-code-review-e2d54b2.md`. + +Goal verification: + +- Verification range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`. +- Result: `passed`, 7/7. +- 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 immutability at the default branch. +- Only authorized scopes changed; ADR governance, all 20 tests, and the diff check passed. +- At review time the remote needed the acceptance commits. That condition has since been satisfied, and CI associated with `e2d54b2` is green as recorded above. +- Report: `planning/adr-0016-acceptance-verification-e2d54b2.md`. + +Adversarial review: + +- Required: Yes. +- Result: `NOT-READY` at exact head `e2d54b26e5d510419885345e22a2374d46aeb710`. This reconciliation commit remediates the recorded findings; final adversarial rerun has not passed yet. +- HIGH: 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 this commit. +- MEDIUM: state and checkpoint still marked completed code review, verification, and CI pending and lacked branch-local code-review and 7/7 verification reports. Disposition: this commit reconciles both records and adds the reports. +- LOW: generic `required checks` wording obscured that ADR Governance is process-required but not GitHub branch-protection-required; branch protection requires only prose, sweep, and sweep SHA reachability, all `not applicable` no-ops here. Disposition: this commit uses explicit wording. +- No content or governance failure: the ADR decision remained unchanged at 497 words, local checks passed, and ADR-0015 alignment was correct. +- Reviewer: OpenAI GPT-5.6-sol, the same provider/model as the earlier review. The implementer provider is unrecorded, so independence evidence is weaker. +- Report: `planning/adr-0016-acceptance-adversarial-e2d54b2.md`. + +Craft Review: + +- Required: Yes. +- Previous proposal result: Pass at `dcf7c8c`; no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-craft-dcf7c8c.md`. +- Previous evidence-remediation result: Pass at `1091016`; no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. +- Acceptance-record result: Not run. The exact-head adversarial `NOT-READY` result blocked it. +- Final Craft Review after this remediation is a mandatory merge condition and has not passed yet. + +Clean-context review: + +- Required: Yes. +- Result: Not run — one-off Jim waiver after the controlled panel attempts were blocked before inference. +- Initial attempt at `dcf7c8c`: blocked before inference because the separate Milestone A activation verdict was absent. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. +- Jim later activated normal and ad-hoc controlled external reviews; activation absence is no longer the current blocker. +- Post-activation attempt at `50f4462`: blocked before inference because the caller-owned disposable root and `brief.md` were missing and the outer filesystem mechanism refused their creation. Report: `planning/adr-0016-clean-context-50f4462.md`. +- Jim then authorized the credential-free brief and disposable root for revision `0df9bfd`; the outer harness's static external-directory denial still blocked creation before inference. +- No model ran, and no same-model substitute review was used. +- Final disposition: Not run; Jim's `waive and present` declaration was recorded in commit `f3f3bdc735d5357ea4a03741163a800510a8b61c` on 2026-08-29 after the controlled panel attempts failed before inference. This one-off waiver applies only to ADR-0016. + +## Drift / Scope Concerns + +The included v0.11.2 audit is historical motivation. A fresh release audit is required before implementation. ADR acceptance does not promote a release or authorize documentation changes. + +Merge commit `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` integrated current base `49e202c818bab1be780b81c28e5d0718cfb89b1c`. Any future content-changing integration requires renewed review. + +## Open Questions / Decisions for Jim + +No further acceptance or merge decision is pending. ADR-0016 is Accepted by Jim, and Jim authorized merge of PR #98 on 2026-08-31. Final adversarial rerun, Craft Review, a focused consistency check as needed, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head are mechanical pre-merge conditions. This authorization does not authorize implementation. + +PR / upstream action gate: + +- PR status: already open and non-draft. +- Merge ready? No — conditional on final adversarial rerun, Craft Review, any needed focused consistency check, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head. +- Jim authorized merge? Yes — on 2026-08-31. + +## Recommended Next Step + +Run the final adversarial rerun, Craft Review, and a focused consistency check as needed. Then obtain green process-required ADR Governance and GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final head and merge PR #98 under Jim's authorization. Do not begin implementation. + +## Handoff Note + +ADR-0016 is Accepted by Jim, and merge authorization is settled. Acceptance-record code review and 7/7 verification passed, and CI associated with `e2d54b2` is green. Exact-head adversarial review at `e2d54b2` returned `NOT-READY`; this commit remediates its PR-body, living-record, report, and CI-wording findings. Final adversarial rerun and Craft Review remain mandatory, with a focused consistency check as needed and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head. Clean-context remains explicitly Jim-waived for ADR-0016. Do not begin implementation. Once merged, ADR-0016 is immutable and later changes require a superseding ADR. diff --git a/planning/released-antd-v0.11.2-audit.md b/planning/released-antd-v0.11.2-audit.md new file mode 100644 index 0000000..49dc66c --- /dev/null +++ b/planning/released-antd-v0.11.2-audit.md @@ -0,0 +1,262 @@ +# Released antd v0.11.2 Audit + +- Date: 2026-08-11 +- Documentation baseline: [`af6d0e9da96dd9b7d31105accbeb9b6a181aaf37`](https://github.com/WithAutonomi/autonomi-developer-docs/commit/af6d0e9da96dd9b7d31105accbeb9b6a181aaf37) +- Emergency branch baseline: `2e11cdc908a04d31bc35a6d998211cdb7949ce93` on `docs/released-antd-safety`, before this audit commit; this local-only historical identifier is unavailable from the remote +- Original audit commit: `16bdb4de6dc6a109b70238b31956685db839318d`; this local-only historical identifier is unavailable from the remote, and the committed branch-local copy of this audit is the reproducible review artifact +- Audit mode: attended knowledge-work checkpoint; no implementation or PR action is authorized + +## Snapshot status + +This is the dated motivating snapshot recorded on 2026-08-11. Its technical findings, exact technical source refs, source links, and evidence limits remain inspectable evidence for Proposed ADR-0016. Its source-of-truth analysis, target-manifest application, recommended remediation, and statements about whether an ADR existed record the policy position before ADR-0016 was proposed. They are preserved as historical context, not as current policy or authorization. + +## Executive verdict + +The result is mixed. Stable `antd` v0.11.2 is the release the affected developer documentation must describe. It restores source-correct ordinary `auto`, `merkle`, and `single` writes and estimates, and its released `ant-core` dependency has strong unit and paid Merkle end-to-end (E2E) coverage. The raw daemon REST response and gRPC contract represent external wave-batch and Merkle preparation correctly, but gRPC has an all-already-stored finalization defect described below. + +The release does not establish a complete daemon-and-binding payment matrix. Six binding defects remain in Python REST, Elixir REST, Lua, Ruby REST, PHP, and Zig. MCP forces the defective Python REST path. Separately, the daemon's gRPC finalize handler rejects the valid all-already-stored wave-batch case, and every typed gRPC binding inherits that server behavior. The exact release evidence contains no wallet-funded daemon REST, gRPC, MCP, or language-binding matrix and no external-signer boundary matrix at 63, 64, 256, and 257 chunks. + +The 45-file emergency branch fixes durable installation and documentation defects, but its v0.11.1 premise and blanket forced-`single` guidance are superseded. It is not publishable as-is. Remediation should start from fresh `origin/main` and selectively port durable fixes. + +## Source-of-truth split + +The repository's two truth needs must remain separate: + +1. **Installation, downloads, package identities, and version claims:** use the latest stable release that a user can obtain. On the audit date that is `antd` v0.11.2, including its downloadable binaries and container images. +2. **Technical behavior tied to released `antd`:** use the v0.11.2 source commit and the dependency chain resolved by that release. This is the correct basis for daemon payment behavior, request and response contracts, and released bindings. +3. **Technical behavior not pinned to released `antd`:** use moving default-branch heads under `current-merged-truth`, selected per page and component. Mixed pages may therefore need separate release and moving-head verification blocks. + +The release split prevents moving source from making unavailable artifacts look installable, while avoiding an old release pin for unrelated architecture and network claims. + +## Stable release and dependency chain + +### ant-sdk v0.11.2 + +- Release: [v0.11.2](https://github.com/WithAutonomi/ant-sdk/releases/tag/v0.11.2), published `2026-08-10T08:35:03Z`. +- Annotated tag object: [`108d64115f5ec5b85a50ec1e24c8c3123e11c502`](https://api.github.com/repos/WithAutonomi/ant-sdk/git/tags/108d64115f5ec5b85a50ec1e24c8c3123e11c502). +- Peeled source commit: [`3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15`](https://github.com/WithAutonomi/ant-sdk/commit/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15). +- `ant-sdk/main` also resolved to `3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15` during this audit. +- The release has 11 downloadable GitHub assets: `antd-darwin-arm64`, `antd-linux-amd64`, `antd-linux-arm64`, `antd-linux-install.sh`, `antd-linux-x64.deb`, `antd-linux-x64.rpm`, `antd-macos.pkg`, `antd-windows-amd64.exe`, `antd-windows-x64-setup.msi`, `antd-windows-x64-setup.wixpdb`, and `SHA256SUMS`. +- The release workflow also publishes `withautonomi/antd:v0.11.2` on [Docker Hub](https://hub.docker.com/r/withautonomi/antd) and `ghcr.io/withautonomi/antd:v0.11.2` on [GitHub Container Registry](https://github.com/orgs/WithAutonomi/packages/container/package/antd). Container images are additional distribution surfaces, not part of the 11-asset GitHub count. + +### Released dependencies + +| Component | Released ref | Exact source | Evidence | +|---|---|---|---| +| `ant-core` in ant-client | `ant-cli-v0.3.2` | [`3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b`](https://github.com/WithAutonomi/ant-client/commit/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b) | [`antd/Cargo.toml`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/Cargo.toml#L7-L10) and [`antd/Cargo.lock`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/Cargo.lock#L805-L810) | +| ant-protocol | `v2.3.1` | [`2566ed454ee82d5bd2588071077911b30284002b`](https://github.com/WithAutonomi/ant-protocol/commit/2566ed454ee82d5bd2588071077911b30284002b) | v2.3.1 release source used by the locked `ant-protocol` 2.3.1 crate | +| evmlib | annotated `v0.9.0` | peeled [`28fc354b3723850cfa7afea10d07a13a0617a035`](https://github.com/WithAutonomi/evmlib/commit/28fc354b3723850cfa7afea10d07a13a0617a035) | [`antd/Cargo.toml`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/Cargo.toml#L8-L11) and locked evmlib 0.9.0 | + +The evmlib tag is annotated; its tag object is distinct from the peeled source commit. The ant-client and ant-protocol refs resolve directly to the commits shown. + +## CI and test evidence + +### ant-sdk + +- [Release run 31369627409](https://github.com/WithAutonomi/ant-sdk/actions/runs/31369627409) is green at the v0.11.2 source SHA. All nine jobs pass: `Build (aarch64-unknown-linux-gnu)`, `Build (x86_64-unknown-linux-gnu)`, `Build (x86_64-pc-windows-msvc)`, `Build (aarch64-apple-darwin)`, `Package Windows (.msi, x64)`, `Docker (multi-arch)`, `Package macOS (.pkg, arm64)`, `Package Linux (deb/rpm/script)`, and `Create Release`. +- [General CI run 31197781579](https://github.com/WithAutonomi/ant-sdk/actions/runs/31197781579) is green at the exact source SHA, but it contains only `Check (antd)`, `Check (antd-rust)`, and `Security audit`. The workflow runs format, clippy, docs, and Rust tests for `antd` and `antd-rust`; it does not run the other bindings or MCP. +- FFI has a separate workflow and surface. It is not evidence that the daemon bindings in the table below were tested. + +### ant-client + +- [CI run 30492539700](https://github.com/WithAutonomi/ant-client/actions/runs/30492539700) and [CI run 30492541939](https://github.com/WithAutonomi/ant-client/actions/runs/30492541939) both pass at exact release SHA `3e6bdd28...`. Their jobs include unit and E2E suites on Linux and macOS, including `Merkle E2E` on both operating systems. +- The separate [pr-checks run 30492541163](https://github.com/WithAutonomi/ant-client/actions/runs/30492541163) failed only `linear-link` and `pr-template`; `self-test` passed. This is Linear/template governance failure, not a code-test failure. + +### Exact core coverage + +The released core evidence establishes the following: + +- [`ant-core/tests/merkle_unit.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/tests/merkle_unit.rs#L17-L120) covers `auto` at 63/64, forced Merkle's one-address rejection and two-address minimum, forced `single`, and partition counts including 65, 256, and 257. +- The inline Merkle tests additionally pin singleton-tail rebalancing and the pre-spend rejection for an external batch above 256 addresses: [`merkle.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/merkle.rs#L2205-L2380). +- [`ant-core/tests/e2e_merkle.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/tests/e2e_merkle.rs#L54-L149) performs forced-Merkle file and in-memory data upload/download round trips. +- The same E2E file pays real local EVM settlements at the 65- and 257-address boundaries and checks complete proof sets and padded-leaf cost scaling: [`e2e_merkle.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/tests/e2e_merkle.rs#L284-L406). + +This coverage does **not** establish either of these matrices: + +- a wallet-funded `antd` REST, gRPC, MCP, and language-binding write matrix; or +- an external-signer 63/64/256/257 prepare, on-chain sign/pay, and finalize matrix. + +## Released behavior matrix + +### Ordinary daemon-funded writes and estimates + +The raw daemon accepts `auto`, `merkle`, and `single`, defaults an absent mode to `auto`, and forwards that mode into ordinary data/file writes and estimates. Relevant sources are [`types.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/types.rs#L382-L400), [`rest/data.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/data.rs#L16-L50), and [`rest/files.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/files.rs#L11-L95). Cost handlers use the same mode parser. + +The released core defaults to `auto`, uses Merkle at 64 or more chunks, allows forced Merkle from two chunks, and keeps forced `single` on the per-chunk path: [`merkle.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/merkle.rs#L165-L176) and [`merkle.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/merkle.rs#L470-L478). + +Ordinary MCP writes use the Python REST client's normal data/file operations and inherit these source-correct modes. They no longer require forced `single`. This statement does not extend to MCP's external-signer tools, which are defective as described below. + +### External signing + +- **Files:** after the already-stored preflight, fewer than 64 payable chunks use wave-batch; 64 through 256 use one Merkle tree; more than 256 are rejected before candidate collection or spend. Sources: [`file.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/file.rs#L1534-L1635) and [`merkle.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/merkle.rs#L452-L468). +- **In-memory data:** external signing is wave-batch-only. Ordinary daemon-funded in-memory data can use Merkle, but [`data_prepare_upload_with_visibility`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/data.rs#L225-L369) explicitly constructs `ExternalPaymentInfo::WaveBatch`. +- **Raw REST:** the daemon returns `payment_type: "wave_batch"` with payments or `payment_type: "merkle"` with depth, pool commitments, and timestamp. Finalize requires the matching `tx_hashes` or `winner_pool_hash`: [`upload.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/upload.rs#L24-L114) and [`upload.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/upload.rs#L194-L356). +- **Raw gRPC:** the proto uses the same `"wave_batch"`/`"merkle"` discriminator and typed fields: [`upload.proto`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/proto/antd/v1/upload.proto#L9-L145). However, when all prepared chunks are already stored, core returns a valid empty wave-batch intent and accepts no-payment finalization, while the gRPC handler removes the pending upload and then rejects the empty `tx_hashes` map. The request fails, the `upload_id` is consumed, and no DataMap result is returned. REST accepts a present empty `tx_hashes` object. Sources: [`file.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/file.rs#L1554-L1562), [`batch.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/batch.rs#L337-L342), [`grpc/service.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/grpc/service.rs#L1078-L1107), and [`rest/upload.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/upload.rs#L223-L267). This is tracked upstream in [`ant-sdk` issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233). + +The raw prepare contracts and ordinary paths are source-correct, but the gRPC finalize edge case above is defective. No funded daemon E2E exercises the complete contracts. + +## Six released binding defects + +All six defects are present at v0.11.2 source commit `3264b514...`. + +1. **Python REST:** `_parse_prepare_result` checks for `payment_type == "merkle_batch"`, while the daemon emits `"merkle"`. It therefore keeps `pool_commitments` empty for a real Merkle response. The gRPC mapper correctly checks `"merkle"`. Sources: [`antd-py/src/antd/_rest.py`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-py/src/antd/_rest.py#L215-L251) and [`antd-py/src/antd/_grpc.py`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-py/src/antd/_grpc.py#L113-L160). +2. **Elixir REST:** `parse_prepare_response` has the same wrong `"merkle_batch"` branch. The gRPC mapper correctly checks `"merkle"`. Sources: [`antd-elixir/lib/antd/client.ex`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-elixir/lib/antd/client.ex#L764-L812) and [`antd-elixir/lib/antd/grpc_client.ex`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-elixir/lib/antd/grpc_client.ex#L807-L854). +3. **Lua:** `build_prepare_result` checks `"merkle_batch"`, so a real `"merkle"` response loses its pool commitments. Source: [`antd-lua/src/antd/client.lua`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-lua/src/antd/client.lua#L250-L304). +4. **Ruby REST:** `parse_prepare_response` checks `"merkle_batch"`; Ruby gRPC correctly checks `"merkle"`. Sources: [`antd-ruby/lib/antd/client.rb`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-ruby/lib/antd/client.rb#L429-L470) and [`antd-ruby/lib/antd/grpc_client.rb`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-ruby/lib/antd/grpc_client.rb#L489-L524). +5. **PHP:** `PrepareUploadResult` is intentionally wave-only, has no typed Merkle fields, and the client exposes only wave `finalizeUpload`; there is no typed Merkle finalize operation. Sources: [`antd-php/src/Models/PrepareUploadResult.php`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-php/src/Models/PrepareUploadResult.php#L6-L39) and [`antd-php/src/AntdClient.php`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-php/src/AntdClient.php#L764-L776), [`AntdClient.php`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-php/src/AntdClient.php#L909-L936). +6. **Zig:** file/data prepare returns raw JSON rather than a typed external-payment model. `finalizeUpload` posts the caller-supplied JSON unchanged, discards its `upload_id` argument, and exposes no typed Merkle finalize operation. Source: [`antd-zig/src/antd.zig`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-zig/src/antd.zig#L430-L457). + +### Why tests mask the defects + +- Python, Elixir, Lua, and Ruby REST tests repeat the incorrect `"merkle_batch"` fixture and assert that shape, rather than feeding the daemon's real `"merkle"` discriminator. Anchors: [Python](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-py/tests/test_rest_client.py#L197-L224), [Elixir](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-elixir/test/antd/client_test.exs#L714-L765), [Lua](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-lua/spec/client_spec.lua#L453-L513), and [Ruby](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-ruby/test/test_client.rb#L363-L426). +- PHP tests cover wave preparation/finalize but no Merkle model or finalize: [`AntdClientTest.php`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-php/tests/AntdClientTest.php#L501-L599). +- Zig tests cover request helpers and chunk finalize but not the broken full-upload body: [`tests.zig`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-zig/src/tests.zig#L317-L451). +- MCP constructs `AsyncAntdClient(transport="rest")`: [`server.py`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-mcp/src/antd_mcp/server.py#L13-L30). For a real `payment_type: "merkle"`, Python REST preserves the discriminator but produces an empty commitment list, which MCP serializes as `pool_commitments: []`: [`server.py`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-mcp/src/antd_mcp/server.py#L545-L570). MCP tests mock the client above the parser and therefore never exercise this failure: [`test_server.py`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd-mcp/tests/test_server.py#L138-L193). + +## All-binding snapshot + +`A/M/S` means ordinary `auto`, `merkle`, and `single` data/file writes and estimates. “Source-correct” does not mean funded runtime-verified. The exact-release column records evidence actually run at the release SHA, not tests that exist only in a source tree. + +| Surface | Ordinary modes | External-signer source result | Exact-release test evidence | Public installability at audit date | +|---|---|---|---|---| +| C++ | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored gRPC finalize defect | None in exact-SHA general CI | Source-only; no public package | +| C# | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored gRPC finalize defect | None in exact-SHA general CI | Source-only; no NuGet package | +| Dart | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored gRPC finalize defect | None in exact-SHA general CI | Source package name `antd` collides on pub.dev | +| Elixir | A/M/S source-correct | REST defective; gRPC mapping inherits all-already-stored finalize defect | None; REST fixture repeats defect | Source-only; no Hex package | +| Go | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored finalize defect | No Go test job at exact release SHA | **Public:** Go proxy `v0.11.2` resolves to `antd-go/v0.11.2` at `3264b514...` | +| Java | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored finalize defect | None in exact-SHA general CI | Source-only; no intended Maven artifact resolved | +| JavaScript / TypeScript | A/M/S source-correct | REST wave/Merkle source-correct | None in exact-SHA general CI | Source package name `antd` collides with Ant Design on npm | +| Kotlin | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored finalize defect | None in exact-SHA general CI | Source-only; no intended Maven artifact resolved | +| Lua | A/M/S source-correct | REST defective discriminator | None; fixture repeats defect | Source-only; no intended LuaRocks package resolved | +| PHP | A/M/S source-correct | Wave-only model/finalize; no typed Merkle | None; wave mocks only | Source-only; no intended Packagist package resolved | +| Python | A/M/S source-correct | REST parser defective; gRPC mapping inherits all-already-stored finalize defect | None; REST fixture repeats defect | Exact-source install route identified from source metadata; no clean-install or runtime verification; no PyPI release | +| Ruby | A/M/S source-correct | REST parser defective; gRPC mapping inherits all-already-stored finalize defect | None; REST fixture repeats defect | Source-only; no intended RubyGems package resolved | +| Rust | A/M/S source-correct | REST source-correct; gRPC mapping inherits all-already-stored finalize defect | `Check (antd-rust)` runs tests | Exact-source install route identified from source metadata; no clean-install or runtime verification; no crates.io package | +| Swift | A/M/S source-correct | Typed gRPC wave/Merkle mapping; inherits all-already-stored finalize defect | None in exact-SHA general CI | Source-only; no public package release | +| Zig | A/M/S source-correct | Raw JSON; full finalize drops `upload_id`; no typed Merkle | None; no full-upload finalize test | Source-only; no public package | +| MCP | Direct A/M/S writes source-correct | Defective because it forces Python REST | None; mocks sit above parser | Source-only Python project; no public MCP package | + +The Go proxy identity is `github.com/WithAutonomi/ant-sdk/antd-go@v0.11.2`. Source metadata identifies exact-Git-source install routes for Python and Rust, but this audit did not clean-install or runtime-verify them, and they are not PyPI or crates.io releases. npm's `antd` is Ant Design, and pub.dev's `antd` is also unrelated. The FFI/mobile surface is separate from these daemon bindings and should not be used to infer binding package support. + +## Moving-head snapshot and drift + +These moving heads were resolved on 2026-08-11 for claims that remain under `current-merged-truth`: + +| Repository | Default branch | Audit head | +|---|---|---| +| ant-sdk | `main` | [`3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15`](https://github.com/WithAutonomi/ant-sdk/commit/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15) | +| ant-client | `main` | [`d4b6fbc1ec5dd957734b4de3b2f463233a7dfdb2`](https://github.com/WithAutonomi/ant-client/commit/d4b6fbc1ec5dd957734b4de3b2f463233a7dfdb2) | +| ant-node | `main` | [`187cbb1909e1492a67fe9dea70d3ff163f8e889d`](https://github.com/WithAutonomi/ant-node/commit/187cbb1909e1492a67fe9dea70d3ff163f8e889d) | +| saorsa-core | `main` | [`5bdc200aee2a6977e5179b757280730e43251b37`](https://github.com/WithAutonomi/saorsa-core/commit/5bdc200aee2a6977e5179b757280730e43251b37) | +| saorsa-transport | `main` | [`c27773fadff58e91901c319c1a3bfaecec3dcaeb`](https://github.com/WithAutonomi/saorsa-transport/commit/c27773fadff58e91901c319c1a3bfaecec3dcaeb) | +| saorsa-pqc | `main` | [`4fbb31d3d29f710726edd32e12ce7b1f64a2aae1`](https://github.com/saorsa-labs/saorsa-pqc/commit/4fbb31d3d29f710726edd32e12ce7b1f64a2aae1) | +| self_encryption | `master` | [`4021f663612c5b963bef935b277eb65416b7d958`](https://github.com/WithAutonomi/self_encryption/commit/4021f663612c5b963bef935b277eb65416b7d958) | +| evmlib | `main` | [`88e20df634f7c80f16777d38a1598c9b651b41b5`](https://github.com/WithAutonomi/evmlib/commit/88e20df634f7c80f16777d38a1598c9b651b41b5) | +| ant-merkle | `master` | [`176ab0a1cafaeee712b3442d9d5af09769149d31`](https://github.com/WithAutonomi/ant-merkle/commit/176ab0a1cafaeee712b3442d9d5af09769149d31) | +| ant-protocol | `main` | [`54c93a8de885ec8e822581381905ea034866d2fe`](https://github.com/WithAutonomi/ant-protocol/commit/54c93a8de885ec8e822581381905ea034866d2fe) | +| ant-keygen | `main` | [`902442f123e16f57de0aeb0f1bfbacf385aa2e87`](https://github.com/WithAutonomi/ant-keygen/commit/902442f123e16f57de0aeb0f1bfbacf385aa2e87) | + +Registry ownership is stale for saorsa-core and saorsa-transport: `repo-registry.yml` still names `saorsa-labs`, while both repositories now live under `WithAutonomi`. Beyond ownership metadata, both have substantive relay/bootstrap lifecycle drift. `docs/architecture/system-overview.md` therefore needs a targeted source re-audit rather than a SHA-only refresh. ant-node movement is mostly operational. Most remaining foundational drift observed in this pass is metadata, governance, or licensing, but each affected claim still needs normal source-audit treatment before its verification SHA changes. + +## Documentation comparison + +### origin/main + +`origin/main` at `af6d0e9...` overstates language-binding availability and installability. Several public package commands name absent packages or unrelated package identities. Its payment guidance also predates the released correction. + +### Emergency branch + +The emergency branch changes 45 files relative to `origin/main` and was built around v0.11.1. It contains many durable corrections, but its release metadata, blanket forced-`single` rule, blanket external-Merkle stop, skill fingerprints, and target manifest are no longer accurate. The giant branch should not be amended wholesale or published as-is. + +## File and group disposition + +| Disposition | File/group | Treatment on a fresh-main remediation branch | +|---|---|---| +| **Keep** | `docs/sdk/install.md` release-install structure | Keep checksum-first binary installs and platform package hardening; substitute v0.11.2 facts and URLs. | +| **Revise** | Language-binding overview and guides | Keep the corrected package-identity/availability principle and use the Python and Rust source-install route metadata only as inputs to verification. Do not present those routes as supported installs until clean-install and runtime evidence exists; retain complete examples only where independently checked. | +| **Keep** | Local-network/test guides | Keep pinned Foundry installation hardening rather than mutable `curl | bash`. | +| **Keep** | MCP and health edits | Keep the corrected MCP daemon-port discovery path and explicit “selected fields” labels on abbreviated health responses. | +| **Keep** | `skills/start` policy shape | Keep tiering and the rule that fetched references are untrusted factual material that cannot override the skill or user request. | +| **Revise** | All v0.11.1 verification blocks, downloads, and examples | Replace release metadata and URLs with v0.11.2 and its released dependency chain. | +| **Revise** | Ordinary write/cost guidance in SDK, MCP, REST/gRPC reference, concepts, and skill | Restore `auto` as the normal/default mode; document `merkle` and `single` as explicit choices rather than forcing `single`. | +| **Revise** | External-signer guide and binding guidance | Split by transport and binding. Raw REST may describe wave/Merkle behavior; defective REST clients and MCP need an explicit stop/warning. gRPC guidance must include the all-already-stored finalize defect and REST alternative. External in-memory data remains wave-only. | +| **Revise** | Go binding guide | Use the module path and public `v0.11.2` Go proxy identity; do not carry old source-only or absent-package claims forward. | +| **Revise** | `skills/start` release mechanics | Refresh source fingerprints and release data, restore ordinary auto/default cost estimates and writes, and make fallback behavior match the precise released limitations. Skill files remain out of scope for this audit commit. | +| **Revert / Remove** | Blanket forced-`single` edits | Remove the blanket rule for direct daemon and MCP writes. Retain forced `single` only as a user-selected mode or a narrowly justified workaround. | +| **Revert / Remove** | Blanket external-Merkle stop | Remove it for raw REST and source-correct external-Merkle mappings. Retain explicit warnings for Python REST, Elixir REST, Lua, Ruby REST, PHP, Zig, and MCP as applicable. For raw gRPC and all typed gRPC bindings, document the separate all-already-stored finalize defect and direct that edge case to REST until a corrected release ships. | +| **Defer** | Mobile FFI and unsupported package guides | Do not promote the separate FFI surface or create guides for package identities that are absent or unrelated. | +| **Defer** | Runnable write-journey verification | Do not mark wallet-funded daemon, MCP, or binding write journeys verified until a funded runtime matrix runs. Source inspection is insufficient for runnable claims. | +| **Defer / New work** | Registry and architecture | Correct saorsa-core/transport ownership in a separately approved slice and re-audit relay/bootstrap lifecycle claims in the system overview. | + +The selective port should cover the branch's durable changes in `docs/sdk/install.md`, language-binding pages, local-network/test pages, MCP pages, health examples, and the skill policy structure. Payment prose, release metadata, `target-manifest.yml`, and skill release mechanics require new v0.11.2 work rather than mechanical cherry-picks. + +## Target-manifest application + +The existing manifest exit says the first corrected stable release must have downloadable assets, `ant-cli-v0.3.2` or later, and “the full payment matrix passing.” v0.11.2 meets the first two conditions and has green core Merkle CI, including paid 65/257 boundaries. It does not meet a literal complete daemon/binding/external-signer matrix because that matrix was not run. The phrase “full payment matrix” is underspecified: it does not define interfaces, modes, boundaries, funding, or required bindings. + +The old v0.11.1 pins cannot remain in place. v0.11.2 is the latest stable security release, is publicly downloadable, and fixes direct Merkle behavior. + +ADR-0003 and the original implementation plan already define `target-manifest` as the mechanism for launch and release hardening. This released-`antd` safety work was designed to apply that mechanism: pin affected user-facing `antd` surfaces to a released dependency set, verify actual behavior, and document defects and safe alternatives. The appropriate bounded action is therefore to repin the affected surface to v0.11.2 and rewrite the manifest's underspecified exit condition around named evidence gaps. + +Repin only the bounded released-`antd` safety surface to v0.11.2 and its released dependency chain. Rewrite manifest scope and exit criteria so they name the unresolved external-signer and binding evidence instead of claiming an undefined full matrix. + +- Bounded scope: release-critical `antd` pages stay on a stable, inspectable set and the manifest explicitly records evidence gaps. Pages about other components are outside this `antd` correction rather than being implicitly certified by the `antd` release. Under ADR-0003 they retain their existing mode until a separately scoped audit changes it. +- Governance: this is an operational use of Accepted ADR-0003's `target-manifest` mode. ADR-0003 governs the mode and verification schema but does not select a particular release. No new ADR is required for the bounded v0.11.2 application. + +Changing the permanent repository-wide default from `current-merged-truth` to released-and-usable truth would be a separate architectural decision requiring a Proposed ADR that supersedes ADR-0003. No such Proposed ADR existed on the audit date. That wider policy question should not block correcting the bounded released-`antd` surface under the mechanism already approved. + +## Recommended remediation shape + +1. Start a fresh branch from `origin/main`, not from the 45-file emergency branch. +2. Selectively port durable installation, package-identity, prerequisite, complete-example, Foundry, MCP discovery, health-label, binding-availability, and skill-policy fixes. +3. Update all release truth to v0.11.2 and state the interface-specific limitations precisely. +4. Restore ordinary direct writes and estimates to `auto` by default. +5. Restrict external-Merkle warnings to defective transports/bindings, keep source-correct guidance available, and document the gRPC all-already-stored finalize defect with REST as the safe alternative. +6. Require a funded runtime matrix before marking runnable write journeys verified. +7. Handle saorsa registry ownership and system-overview drift in separately approved work. + +No PR, push, merge, publish, release, rendered-doc edit, source edit, CI edit, test edit, target-manifest edit, ADR edit, or skill edit is part of this audit slice. + +## Reproducible evidence commands + +Representative commands used for the audit follow. They require `gh`, `curl`, and public network access; none changes repository state. + +The original audit also used a local comparison against `2e11cdc908a04d31bc35a6d998211cdb7949ce93` while that commit was available locally. That comparison is no longer remotely reproducible and is not readiness evidence. This committed audit copy preserves the historical findings. + +```bash +gh release view v0.11.2 --repo WithAutonomi/ant-sdk \ + --json tagName,publishedAt,isDraft,isPrerelease,targetCommitish,assets,url +gh api repos/WithAutonomi/ant-sdk/git/ref/tags/v0.11.2 +gh api repos/WithAutonomi/ant-sdk/git/tags/108d64115f5ec5b85a50ec1e24c8c3123e11c502 + +gh run view 31369627409 --repo WithAutonomi/ant-sdk \ + --json headSha,status,conclusion,url,jobs +gh run view 31197781579 --repo WithAutonomi/ant-sdk \ + --json headSha,status,conclusion,url,jobs +gh run view 30492539700 --repo WithAutonomi/ant-client \ + --json headSha,status,conclusion,url,jobs +gh run view 30492541939 --repo WithAutonomi/ant-client \ + --json headSha,status,conclusion,url,jobs +gh run view 30492541163 --repo WithAutonomi/ant-client \ + --json headSha,status,conclusion,url,jobs + +gh api repos/WithAutonomi/ant-sdk/commits/main +gh api repos/WithAutonomi/ant-client/git/ref/tags/ant-cli-v0.3.2 +gh api repos/WithAutonomi/ant-protocol/git/ref/tags/v2.3.1 +gh api repos/WithAutonomi/evmlib/git/ref/tags/v0.9.0 + +curl --fail --silent --show-error \ + https://proxy.golang.org/github.com/withautonomi/ant-sdk/antd-go/@v/v0.11.2.info +``` + +Canonical source URLs are linked in each findings section. Moving-head queries used `gh api repos///commits/` on 2026-08-11. + +## Uncertainties and evidence limits + +- No broad documentation CI arbiter covers this manual branch; local evidence is weaker and cannot be called docs CI-green. +- No wallet-funded runtime daemon matrix was run for REST, gRPC, MCP, or bindings. +- No external-signer funded boundary matrix was run at 63, 64, 256, and 257. +- Exact-release general CI does not run Python, C++, C#, Dart, Elixir, Go, Java, JavaScript/TypeScript, Kotlin, Lua, PHP, Ruby, Swift, Zig, or MCP tests. Existing source tests do not substitute for exact-release CI, and several mask the defects above. +- Public registries can change after the audit timestamp. Go proxy v0.11.2 was the only intended public binding identity resolved during the audit. Python and Rust exact-source install routes were identified from source metadata but were not clean-install or runtime-verified, and they are not public package releases. +- Moving heads are a dated snapshot, not stable release pins. Technical claims must be re-audited if those SHAs move before remediation. +- The audit did not edit `target-manifest.yml`. At the audit date, the intended bounded next step was to repin its released-`antd` scope to v0.11.2 under ADR-0003, subject to approval of the remediation slice.