From 5716bbe539c352b7da880b3a0ad54dd3d475e546 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Wed, 12 Aug 2026 17:41:17 +0100 Subject: [PATCH 01/26] docs(adr): propose released truth for public docs --- ...eleased-truth-for-public-developer-docs.md | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 adr/ADR-0016-released-truth-for-public-developer-docs.md 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..4e029a6 --- /dev/null +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -0,0 +1,109 @@ +# ADR-0016: Released truth for public developer documentation + +- **Status:** Proposed +- **Date:** 2026-08-12 +- **Decision owners:** Jim Collinson +- **Reviewers:** Jim Collinson +- **Supersedes:** ADR-0003 (source-selection default and verification-mode set only); ADR-0004 (default-branch metadata-restamp semantics only) +- **Superseded by:** none +- **Related:** ADR-0005 through ADR-0007; ADR-0012 through ADR-0014; `planning/verification-workflow.md`; `planning/implementation-plan.md` §5; `WithAutonomi/ant-sdk` v0.11.2 audit; [WithAutonomi/ant-sdk issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233) + +## Context + +ADR-0003 made `current-merged-truth` the default source for public developer documentation. This prevented speculative documentation of unmerged branches, but it did not prevent a different failure: a default branch can contain code that has not been released, is not available through a supported installation route, is incompatible with the deployed Autonomi Network, or has not been proven usable through the interface the page recommends. + +That gap can make rendered documentation describe what source code intends rather than what a developer can obtain and build against. The `antd` v0.11.2 audit exposed the practical consequences. The stable release corrected ordinary Merkle writes, while several released binding and Model Context Protocol (MCP) external-signing paths remained defective or unavailable. The gRPC service also rejects a valid all-already-stored finalization and consumes its upload identifier, tracked in `ant-sdk` issue #233. Neither moving source nor the existence of an API shape is enough to call a developer journey available. + +The existing `target-manifest` mode can pin a release-hardening pass, but ADR-0003 treats it as an exception and returns public docs to moving default branches afterward. Public developer documentation needs the reverse default: released, obtainable, compatible, evidence-backed behavior is the normal truth; moving source prepares the next documentation release without silently changing the public one. The rendered docs and published developer skill are two delivery forms of that same public guidance, so they must describe one released product surface. + +## Decision Drivers + +- Developers must be able to obtain and use the product surface that the public docs describe. +- Merged but unreleased code must not appear as an available capability. +- A multi-repository product surface must resolve to one compatible, auditable release set. +- Known defects must produce safe guidance, not optimistic claims or silent omission. +- Package and installation claims must distinguish public availability from source-directory presence. +- Exact per-surface provenance and deterministic drift detection must remain intact. +- Future-release work must remain visible without being confused with public released truth. +- Rendered docs and the published developer skill must not describe different product releases or support boundaries. + +## Considered Options + +1. **Retain ADR-0003: moving merged truth by default, with release constraints only for installation and version pages.** Rejected because API, behavior, architecture, examples, and compatibility can also differ between merged source and the released product developers can use. +2. **Make the existing `target-manifest` mode the permanent default.** Rejected because that mode represents an explicitly selected launch or pre-release target. Reusing it for the public released product would conflate what is being hardened with what is already available and supported. +3. **Make released truth the public default and retain a distinct target mode for explicit pre-release hardening or versioned previews.** Chosen because it keeps the public contract honest while preserving preparation for the next release. +4. **Treat release status and public availability as sufficient evidence of usability.** Rejected because an obtainable release can expose a defective or nonfunctional route. Release status proves availability, not that the documented capability works. +5. **Allow each documentation surface to select released refs independently.** Rejected because independent pins cannot establish cross-component or deployed-network compatibility. The public surface needs one auditable release set. + +## Decision + +Public rendered developer documentation and the published developer skill will describe **released truth** by default: the newest coherent set of released component versions that is publicly obtainable through documented standard routes, compatible with one another and the deployed Autonomi Network for the claims made, and supported by capability-specific evidence. + +The verification model will retain exact per-surface provenance while changing its default: + +- **`released-truth` is the default mode for public rendered documentation and the published developer skill.** Verification resolves every documented surface to exact refs in one machine-readable release manifest. A ref may identify a component's own release or the exact dependency ref shipped by another released product. +- **The release manifest represents a coherent product set, not a bag of latest tags.** Component versions, transitive refs that carry documented behavior, and deployed Autonomi Network compatibility must agree for the claims that depend on them. +- **`target-manifest` remains an explicit pre-release, launch-hardening, or release-candidate mode.** It does not become the current public developer surface before release. If target content is published, it must be isolated and clearly labelled as a versioned preview rather than replacing the default docs. +- **`current-merged-truth` is retired as a verification mode for public rendered documentation and the published skill.** Moving default branches remain research inputs for drift detection, impact assessment, and next-release preparation. A merge can open an audit queue; it cannot silently advance rendered prose or verification SHAs. + +Released truth is capability-specific and evidence-based: + +- “Usable” does not mean “bug-free.” A known defect is part of released truth. The docs must state the affected route, boundary, or operation and provide a safe alternative when one exists. +- A broken or unproven route must not be presented as working. Missing evidence requires the page to defer, narrow, stub, or reframe the claim rather than infer success. +- A package, binary, container, binding, or tool is available only when its documented standard installation identity resolves publicly, or when the project explicitly supports a reproducible source-install route that has been verified from a clean environment. Source-directory presence alone is not availability. +- A release is promoted into public docs only after an audit resolves exact component and dependency refs, obtainable artifacts, release-set compatibility, relevant runtime or journey evidence, and known limitations. +- When the newest release is unsuitable as the supported developer baseline, the manifest may retain the prior supported release set. That exception must be explicit, justified by evidence, and visible in the release audit; it must not happen through stale metadata or omission. + +The existing verification-block invariants remain: + +- Every rendered documentation surface carries one or more machine-readable verification records with source repository, ref, exact commit SHA, verification date, and verification mode. +- The published skill carries equivalent exact provenance in its defined metadata surfaces. +- A surface presented as verified never uses `source_commit: TBD`. +- Provenance mechanics remain outside rendered prose, while released defects, limitations, and safe alternatives appear in rendered guidance when developers need them. + +ADR-0004 continues to govern deterministic detection and model-tiered auditing, except that this ADR supersedes its default-branch metadata-restamp semantics: default-branch movement may create next-release audit input, but released provenance changes only through release promotion. ADR-0005 through ADR-0007 continue to govern scheduling, update-track separation, and fail-closed operation. Detailed manifest schemas, promotion mechanics, migration sequencing, and automation changes belong in a follow-up specification and plan. + +## Consequences + +### Positive + +- Public docs describe what developers can obtain and build against rather than what unreleased source suggests. +- Release, dependency, network, package, and runtime compatibility become one auditable contract. +- Known defects produce actionable guidance and upstream feedback instead of false confidence. +- Moving source remains monitored without silently changing the public product story. +- Exact provenance, fail-closed behavior, and the source-audit discipline from ADR-0003 are preserved. + +### Negative / Trade-offs + +- Documentation can intentionally lag merged source until a release is promoted. +- Maintaining a coherent manifest across multiple repositories and deployed-network dependencies adds release-management work. +- If release promotion is neglected, public docs can become stale even while drift detection is working. +- Capability-specific evidence and known-defect guidance require continuing judgement and maintenance. +- Some source-present bindings or APIs will remain undocumented as supported until an obtainable, verified route exists. + +### Neutral / Operational + +- Default-branch movement still matters: it starts impact assessment and prepares future documentation, but does not itself change released truth. +- Versioned previews may describe a target release when clearly separated from the default public docs. +- Accepted ADR-0003 remains immutable; this ADR's `Supersedes` field is the authoritative supersession link if this proposal is accepted. +- The exact release-manifest shape, migration from existing modes, release-promotion workflow, and automation updates require a separate reviewed specification and execution plan. + +## Validation + +This decision is satisfied when all of the following remain true: + +- Every public installation or package identity resolves through its documented supported route from a clean environment. +- Every public verification record resolves to exact refs in one coherent release manifest, including shipped dependency refs where they carry documented behavior. +- Claims that depend on deployed Autonomi Network behavior are checked against a compatible deployed state. +- Getting-started and how-to journeys have evidence appropriate to the released route they recommend; missing evidence narrows or defers the claim. +- Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. +- No verification record backing the default public rendered documentation or published developer skill uses `current-merged-truth`. +- `target-manifest` content never backs the default public surface; any published target content is isolated as a versioned preview and clearly labelled pre-release. +- Movement on an upstream default branch cannot by itself change public rendered prose, published skill guidance, or released verification SHAs. +- Promotion of a new release leaves an auditable record of artifacts, exact refs, compatibility, journey evidence, and accepted limitations. + +Review triggers include changing the public default away from released truth, allowing merged source to advance public docs without release promotion, weakening artifact or usability evidence, or merging pre-release target content into the default public surface without clear preview isolation. + +## Notes for AI-assisted work + +AI tools helped draft this ADR. It remains **Proposed** until Jim Collinson reviews and accepts it. AI tools must not mark it Accepted. If accepted, future changes require a new superseding ADR rather than edits to this record. From dfabe8febf6e0d9eb680036d8a6933b3a95a4dfe Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Wed, 12 Aug 2026 18:01:03 +0100 Subject: [PATCH 02/26] docs(gsd): record ADR review blockers --- planning/STATE.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 planning/STATE.md diff --git a/planning/STATE.md b/planning/STATE.md new file mode 100644 index 0000000..fcc210a --- /dev/null +++ b/planning/STATE.md @@ -0,0 +1,50 @@ +# GSD State + +## Current Position + +- Phase: released-truth source-of-truth decision +- Plan: supersede ADR-0003 before documentation remediation +- Task: review Proposed ADR-0016 +- Status: adversarial blockers; attended remediation checkpoint +- Mode: attended +- Branch: `adr/released-and-usable-truth` +- Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` +- Proposed ADR commit: `5716bbe539c352b7da880b3a0ad54dd3d475e546` +- Implementation: not started; ADR acceptance remains human-only + +## Decision Intent + +- Public rendered developer documentation and the published developer skill should describe released, publicly obtainable, compatible, capability-evidenced usable truth. +- Known released defects and safe alternatives are part of that truth. +- Moving default branches prepare the next release; they do not silently advance the public documentation. +- `target-manifest` remains pre-release/preview truth; `current-merged-truth` retires from the default public surface. + +## Review State + +- Repo-local ADR review: valid after the first correction pass. +- Goal verification: passed; commit adds only one Proposed ADR and changes no Accepted ADR or implementation. +- Structural validation: ADR governance passed with 1 ADR checked; 20 governance tests passed; `git diff --check` passed. +- Adversarial review: `NOT-READY`. + - HIGH: ADR-0004 supersession must cover default-branch detector/source-resolution semantics for released records, not only restamping. + - HIGH: release promotion needs durable minimum evidence semantics for release identity, clean obtainability, capability/runtime evidence, deployed-network identity, and retaining an older baseline. + - HIGH: the motivating v0.11.2 audit is not reproducible from this branch or an immutable link. + - MEDIUM: skill capability/defect consistency needs explicit validation, not only matching refs. + - MEDIUM: rendered installation/version guidance must identify an older supported baseline when a newer public release is unsuitable. +- Craft Review: concerns. + - CONFORMANCE: add template-aligned prospective Acceptance metadata. + - CONFORMANCE: replace the informal audit reference with an inspectable immutable artifact. + - CONFORMANCE: replace British spellings with repo-required American English. +- Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. + - `models: unavailable (auth) · 0s` +- CI arbiter: no remote branch/PR exists; local evidence is weaker and must not be called CI-green. + +## Constraints + +- Do not edit Accepted ADR-0003 or ADR-0004. +- Do not mark ADR-0016 Accepted autonomously. +- Do not implement manifest, tooling, policy, or rendered-documentation changes before the ADR decision gate. +- Do not open a PR without Jim's explicit confirmation. + +## Next + +- Remediate the Proposed ADR and evidence reproducibility findings, rerun ADR review, verification, adversarial, Craft, and the deferred clean-context gate, then return to Jim for the human acceptance decision. From 735091d7ed55db90eb48129c879796dc6ebfe963 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 17 Aug 2026 18:08:18 +0100 Subject: [PATCH 03/26] docs(adr): define released-truth promotion evidence - Supersede released source-resolution and drift semantics\n- Add branch-local v0.11.2 audit evidence --- ...eleased-truth-for-public-developer-docs.md | 40 ++- planning/released-antd-v0.11.2-audit.md | 266 ++++++++++++++++++ 2 files changed, 295 insertions(+), 11 deletions(-) create mode 100644 planning/released-antd-v0.11.2-audit.md diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md index 4e029a6..25389b6 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -1,12 +1,13 @@ # ADR-0016: Released truth for public developer documentation - **Status:** Proposed +- **Acceptance:** Prospective — pending review and explicit acceptance by Jim Collinson as decision owner. - **Date:** 2026-08-12 - **Decision owners:** Jim Collinson - **Reviewers:** Jim Collinson -- **Supersedes:** ADR-0003 (source-selection default and verification-mode set only); ADR-0004 (default-branch metadata-restamp semantics only) +- **Supersedes:** ADR-0003 (source-selection default and verification-mode set only); ADR-0004 (source resolution and drift semantics for the default public surface only) - **Superseded by:** none -- **Related:** ADR-0005 through ADR-0007; ADR-0012 through ADR-0014; `planning/verification-workflow.md`; `planning/implementation-plan.md` §5; `WithAutonomi/ant-sdk` v0.11.2 audit; [WithAutonomi/ant-sdk issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233) +- **Related:** ADR-0005 through ADR-0007; ADR-0012 through ADR-0014; `planning/verification-workflow.md`; `planning/implementation-plan.md` §5; `planning/released-antd-v0.11.2-audit.md`; [WithAutonomi/ant-sdk issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233) ## Context @@ -14,6 +15,8 @@ ADR-0003 made `current-merged-truth` the default source for public developer doc That gap can make rendered documentation describe what source code intends rather than what a developer can obtain and build against. The `antd` v0.11.2 audit exposed the practical consequences. The stable release corrected ordinary Merkle writes, while several released binding and Model Context Protocol (MCP) external-signing paths remained defective or unavailable. The gRPC service also rejects a valid all-already-stored finalization and consumes its upload identifier, tracked in `ant-sdk` issue #233. Neither moving source nor the existence of an API shape is enough to call a developer journey available. +The inspectable audit in `planning/released-antd-v0.11.2-audit.md` records the exact release refs, artifact identities, continuous integration (CI) evidence, behavior matrix, known defects, and evidence gaps that motivated this proposal. It is a dated evidence snapshot, not a replacement for canonical release artifacts or source. Its policy recommendation predates this ADR and is preserved as historical context, not as current authority. + The existing `target-manifest` mode can pin a release-hardening pass, but ADR-0003 treats it as an exception and returns public docs to moving default branches afterward. Public developer documentation needs the reverse default: released, obtainable, compatible, evidence-backed behavior is the normal truth; moving source prepares the next documentation release without silently changing the public one. The rendered docs and published developer skill are two delivery forms of that same public guidance, so they must describe one released product surface. ## Decision Drivers @@ -37,22 +40,34 @@ The existing `target-manifest` mode can pin a release-hardening pass, but ADR-00 ## Decision -Public rendered developer documentation and the published developer skill will describe **released truth** by default: the newest coherent set of released component versions that is publicly obtainable through documented standard routes, compatible with one another and the deployed Autonomi Network for the claims made, and supported by capability-specific evidence. +Public rendered developer documentation and the published developer skill will describe **released truth** by default: the newest coherent release set that passes the mandatory public-baseline evidence below. The release set must be publicly obtainable through documented standard routes, compatible with its shipped dependencies and the deployed Autonomi Network for the claims made, and supported by capability-specific evidence. The verification model will retain exact per-surface provenance while changing its default: - **`released-truth` is the default mode for public rendered documentation and the published developer skill.** Verification resolves every documented surface to exact refs in one machine-readable release manifest. A ref may identify a component's own release or the exact dependency ref shipped by another released product. - **The release manifest represents a coherent product set, not a bag of latest tags.** Component versions, transitive refs that carry documented behavior, and deployed Autonomi Network compatibility must agree for the claims that depend on them. -- **`target-manifest` remains an explicit pre-release, launch-hardening, or release-candidate mode.** It does not become the current public developer surface before release. If target content is published, it must be isolated and clearly labelled as a versioned preview rather than replacing the default docs. +- **`target-manifest` remains an explicit pre-release, launch-hardening, or release-candidate mode.** It does not become the current public developer surface before release. If target content is published, it must be isolated and clearly labeled as a versioned preview rather than replacing the default docs. - **`current-merged-truth` is retired as a verification mode for public rendered documentation and the published skill.** Moving default branches remain research inputs for drift detection, impact assessment, and next-release preparation. A merge can open an audit queue; it cannot silently advance rendered prose or verification SHAs. +Every candidate release set requires a committed, machine-readable release manifest and an inspectable promotion record. Promotion fails closed if any mandatory field or evidence is absent. The record must contain, at minimum: + +- **Immutable release identity:** the public version and release URL for each component, immutable tag object and peeled source commit where applicable, exact shipped dependency refs, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable. +- **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. +- **Release-set compatibility and deployed-network identity:** locked dependency evidence for the shipped set and, for network-dependent claims, the network environment, observation date, protocol or configuration anchor, and the most precise inspectable deployment identity available. If the deployed state cannot be identified precisely enough to reproduce a claim, that claim remains unverified and cannot be promoted. +- **Capability and runtime evidence:** a matrix mapping each public interface, capability, and material operation to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. +- **Known limitations and alternatives:** known defects, affected versions and operations, upstream issue links for material defects, and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when the supported usage remains safe and reproducible; otherwise the capability is `unavailable` or `deferred`. +- **Cross-surface consistency:** the public docs and published developer skill must map every covered interface and capability to the same support status, known defect or limitation, and safe alternative. Matching refs alone is insufficient. A mismatch blocks promotion. +- **Objective supported-baseline retention:** the incumbent supported release set, the candidate release set, each result against the predeclared mandatory public baseline, and the resulting promote-or-retain outcome. A candidate replaces the incumbent only when every mandatory promotion requirement passes. If any requirement fails, the incumbent remains the supported default; if no incumbent exists, the candidate remains unpromoted. + +The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. The prior supported release set remains the default until a candidate passes every promotion requirement. When a newer available release is unsuitable, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command; retaining an older baseline through stale metadata or omission is prohibited. + Released truth is capability-specific and evidence-based: - “Usable” does not mean “bug-free.” A known defect is part of released truth. The docs must state the affected route, boundary, or operation and provide a safe alternative when one exists. - A broken or unproven route must not be presented as working. Missing evidence requires the page to defer, narrow, stub, or reframe the claim rather than infer success. - A package, binary, container, binding, or tool is available only when its documented standard installation identity resolves publicly, or when the project explicitly supports a reproducible source-install route that has been verified from a clean environment. Source-directory presence alone is not availability. -- A release is promoted into public docs only after an audit resolves exact component and dependency refs, obtainable artifacts, release-set compatibility, relevant runtime or journey evidence, and known limitations. -- When the newest release is unsuitable as the supported developer baseline, the manifest may retain the prior supported release set. That exception must be explicit, justified by evidence, and visible in the release audit; it must not happen through stale metadata or omission. +- A release is promoted into public docs only when its manifest and promotion record satisfy the mandatory fields and evidence floors in this decision. +- Non-baseline capabilities do not block the whole release set when their status and guidance are honest. They remain `unavailable` or `deferred`, or `supported-with-known-limitation` when a safe, verified usage boundary exists. The existing verification-block invariants remain: @@ -61,7 +76,7 @@ The existing verification-block invariants remain: - A surface presented as verified never uses `source_commit: TBD`. - Provenance mechanics remain outside rendered prose, while released defects, limitations, and safe alternatives appear in rendered guidance when developers need them. -ADR-0004 continues to govern deterministic detection and model-tiered auditing, except that this ADR supersedes its default-branch metadata-restamp semantics: default-branch movement may create next-release audit input, but released provenance changes only through release promotion. ADR-0005 through ADR-0007 continue to govern scheduling, update-track separation, and fail-closed operation. Detailed manifest schemas, promotion mechanics, migration sequencing, and automation changes belong in a follow-up specification and plan. +ADR-0004 continues to govern deterministic detection, fail-closed behavior, and model-tiered auditing, but this ADR supersedes its source-resolution and drift semantics for the default public surface. Released-record conformance and next-release source movement are separate detector outcomes. A released-truth record resolves through the active release manifest, not through the repository registry plus a GitHub default branch; deterministic comparison against that manifest detects corruption or inconsistency in released records. Default branches remain registry-resolved watch inputs and are compared with a separately tracked, last-audited watch state. Their movement creates next-release impact candidates, but does not mark released records stale, authorize a metadata re-stamp, or advance released provenance. Completing a next-release impact audit may advance the watch state without changing the released record. Metadata-only and prose audit tiers remain, but public SHAs change only through release promotion. ADR-0005 through ADR-0007 continue to govern scheduling, update-track separation, and fail-closed operation. Detailed manifest and watch-state schemas, promotion and detection mechanics, migration sequencing, and automation changes belong in a follow-up specification and plan. ## Consequences @@ -78,7 +93,7 @@ ADR-0004 continues to govern deterministic detection and model-tiered auditing, - Documentation can intentionally lag merged source until a release is promoted. - Maintaining a coherent manifest across multiple repositories and deployed-network dependencies adds release-management work. - If release promotion is neglected, public docs can become stale even while drift detection is working. -- Capability-specific evidence and known-defect guidance require continuing judgement and maintenance. +- Capability-specific evidence and known-defect guidance require continuing judgment and maintenance. - Some source-present bindings or APIs will remain undocumented as supported until an obtainable, verified route exists. ### Neutral / Operational @@ -94,11 +109,14 @@ This decision is satisfied when all of the following remain true: - Every public installation or package identity resolves through its documented supported route from a clean environment. - Every public verification record resolves to exact refs in one coherent release manifest, including shipped dependency refs where they carry documented behavior. -- Claims that depend on deployed Autonomi Network behavior are checked against a compatible deployed state. -- Getting-started and how-to journeys have evidence appropriate to the released route they recommend; missing evidence narrows or defers the claim. +- Every release promotion record contains all seven minimum evidence groups required by this decision and identifies the predeclared mandatory public baseline. +- Claims that depend on deployed Autonomi Network behavior are checked against the identified compatible deployed state; claims without a reproducible deployment anchor remain unverified. +- Getting-started and how-to journeys have complete runtime evidence for the released interface they recommend; source or schema inspection alone does not pass. - Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. +- Every covered capability has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. +- If a newer available release fails the mandatory baseline, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command. - No verification record backing the default public rendered documentation or published developer skill uses `current-merged-truth`. -- `target-manifest` content never backs the default public surface; any published target content is isolated as a versioned preview and clearly labelled pre-release. +- `target-manifest` content never backs the default public surface; any published target content is isolated as a versioned preview and clearly labeled pre-release. - Movement on an upstream default branch cannot by itself change public rendered prose, published skill guidance, or released verification SHAs. - Promotion of a new release leaves an auditable record of artifacts, exact refs, compatibility, journey evidence, and accepted limitations. 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..e4c2897 --- /dev/null +++ b/planning/released-antd-v0.11.2-audit.md @@ -0,0 +1,266 @@ +# 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`](https://github.com/WithAutonomi/autonomi-developer-docs/commit/2e11cdc908a04d31bc35a6d998211cdb7949ce93) on `docs/released-antd-safety`, before this audit commit +- Original audit commit: [`16bdb4de6dc6a109b70238b31956685db839318d`](https://github.com/WithAutonomi/autonomi-developer-docs/commit/16bdb4de6dc6a109b70238b31956685db839318d); copied into this proposal branch so review is reproducible from the branch alone +- 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 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/3264b514dac9ed361a7426d6d5ae6a8e7b6b15/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 installable at SHA; 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 installable at SHA; 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`. Python and Rust can be installed from the exact Git source, but this is not a PyPI or crates.io release. 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. | +| **Keep** | Language-binding overview and guides | Keep corrected package-identity/availability principle, source-pinned Python and Rust installs with prerequisites, and complete examples that were 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. + +```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 +gh api \ + "repos/WithAutonomi/autonomi-developer-docs/compare/af6d0e9da96dd9b7d31105accbeb9b6a181aaf37...2e11cdc908a04d31bc35a6d998211cdb7949ce93" \ + --jq '.files[].filename' +gh api \ + "repos/WithAutonomi/autonomi-developer-docs/compare/af6d0e9da96dd9b7d31105accbeb9b6a181aaf37...2e11cdc908a04d31bc35a6d998211cdb7949ce93" \ + --jq '{changed_files: (.files | length), additions: ([.files[].additions] | add), deletions: ([.files[].deletions] | add)}' +``` + +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 installs 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. From f7639fb16789cf700d7cf00754d31327b4cc70a8 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 17 Aug 2026 18:16:11 +0100 Subject: [PATCH 04/26] docs(gsd): record ADR code review blockers --- planning/STATE.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index fcc210a..7c8cd27 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,12 +4,12 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: review Proposed ADR-0016 -- Status: adversarial blockers; attended remediation checkpoint +- Task: remediate Proposed ADR-0016 review findings +- Status: code-review blockers; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` -- Proposed ADR commit: `5716bbe539c352b7da880b3a0ad54dd3d475e546` +- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; remediation `735091d7ed55db90eb48129c879796dc6ebfe963` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -21,19 +21,12 @@ ## Review State -- Repo-local ADR review: valid after the first correction pass. -- Goal verification: passed; commit adds only one Proposed ADR and changes no Accepted ADR or implementation. -- Structural validation: ADR governance passed with 1 ADR checked; 20 governance tests passed; `git diff --check` passed. -- Adversarial review: `NOT-READY`. - - HIGH: ADR-0004 supersession must cover default-branch detector/source-resolution semantics for released records, not only restamping. - - HIGH: release promotion needs durable minimum evidence semantics for release identity, clean obtainability, capability/runtime evidence, deployed-network identity, and retaining an older baseline. - - HIGH: the motivating v0.11.2 audit is not reproducible from this branch or an immutable link. - - MEDIUM: skill capability/defect consistency needs explicit validation, not only matching refs. - - MEDIUM: rendered installation/version guidance must identify an older supported baseline when a newer public release is unsuitable. -- Craft Review: concerns. - - CONFORMANCE: add template-aligned prospective Acceptance metadata. - - CONFORMANCE: replace the informal audit reference with an inspectable immutable artifact. - - CONFORMANCE: replace British spellings with repo-required American English. +- Remediation commit `735091d` addresses the first 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. +- Structural validation after remediation: ADR governance passed with 1 ADR checked; 20 governance tests passed; `git diff --check origin/main...HEAD` passed; worktree was clean. +- Independent code review: `issues_found`. + - HIGH: the retained-incumbent rule can preserve a release that has itself become withdrawn, insecure, network-incompatible, or baseline-noncompliant. Retention must require the incumbent still to pass applicable safety and baseline requirements; otherwise guidance must narrow or state that no supported baseline exists. + - MEDIUM: the audit calls Python and Rust exact-source routes installable without clean-install commands/results. Add reproducible evidence or relabel them as identified but not runtime-verified. +- Goal verification, adversarial re-review, and Craft re-review have not run on remediation commit `735091d` because code review blocked advancement. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: no remote branch/PR exists; local evidence is weaker and must not be called CI-green. @@ -47,4 +40,4 @@ ## Next -- Remediate the Proposed ADR and evidence reproducibility findings, rerun ADR review, verification, adversarial, Craft, and the deferred clean-context gate, then return to Jim for the human acceptance decision. +- With Jim's attended approval, add the incumbent-disqualification invariant and correct the audit's Python/Rust installability evidence labels, then rerun code review, goal verification, adversarial, Craft, and the deferred clean-context gate before returning for the human acceptance decision. From 57ec56cb90db89583603f4cf075c9f7d272a9b87 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 14:23:01 +0100 Subject: [PATCH 05/26] docs(adr): qualify released-truth fallback - Disqualify incumbents that no longer meet released baseline requirements - Relabel unverified Python and Rust source-install routes --- ...DR-0016-released-truth-for-public-developer-docs.md | 7 ++++--- planning/released-antd-v0.11.2-audit.md | 10 +++++----- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md index 25389b6..b80ee8b 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -57,9 +57,9 @@ Every candidate release set requires a committed, machine-readable release manif - **Capability and runtime evidence:** a matrix mapping each public interface, capability, and material operation to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. - **Known limitations and alternatives:** known defects, affected versions and operations, upstream issue links for material defects, and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when the supported usage remains safe and reproducible; otherwise the capability is `unavailable` or `deferred`. - **Cross-surface consistency:** the public docs and published developer skill must map every covered interface and capability to the same support status, known defect or limitation, and safe alternative. Matching refs alone is insufficient. A mismatch blocks promotion. -- **Objective supported-baseline retention:** the incumbent supported release set, the candidate release set, each result against the predeclared mandatory public baseline, and the resulting promote-or-retain outcome. A candidate replaces the incumbent only when every mandatory promotion requirement passes. If any requirement fails, the incumbent remains the supported default; if no incumbent exists, the candidate remains unpromoted. +- **Objective supported-baseline retention:** the incumbent supported release set, the candidate release set, each result against the predeclared mandatory public baseline, and the resulting promote-or-retain outcome. A candidate replaces the incumbent only when every mandatory promotion requirement passes. If any requirement fails, the incumbent remains the supported default only for journeys where it continues to satisfy applicable obtainability, safety and security, deployed-network compatibility, and mandatory baseline requirements. A withdrawn or unobtainable, unsafe or insecure, incompatible, or baseline-noncompliant incumbent is disqualified for the affected journey. If no qualifying incumbent exists, the candidate remains unpromoted, affected guidance is narrowed or withdrawn, and public guidance explicitly states that no supported baseline exists for that journey until a released candidate passes. -The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. The prior supported release set remains the default until a candidate passes every promotion requirement. When a newer available release is unsuitable, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command; retaining an older baseline through stale metadata or omission is prohibited. +The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. Subject to the incumbent qualification rule above, the prior supported release set remains the default until a candidate passes every promotion requirement. When a newer available release is unsuitable and the incumbent remains qualified, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command; retaining an older baseline through stale metadata or omission is prohibited. When the incumbent is disqualified, the affected guidance must instead narrow or withdraw the journey and state that no supported baseline exists until a released candidate passes. Released truth is capability-specific and evidence-based: @@ -114,7 +114,8 @@ This decision is satisfied when all of the following remain true: - Getting-started and how-to journeys have complete runtime evidence for the released interface they recommend; source or schema inspection alone does not pass. - Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. - Every covered capability has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. -- If a newer available release fails the mandatory baseline, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command. +- If a newer available release fails the mandatory baseline and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command. +- If an incumbent becomes withdrawn or unobtainable, unsafe or insecure, incompatible with the deployed Autonomi Network, or noncompliant with the mandatory baseline, affected guidance narrows or withdraws the journey and states that no supported baseline exists until a released candidate passes. - No verification record backing the default public rendered documentation or published developer skill uses `current-merged-truth`. - `target-manifest` content never backs the default public surface; any published target content is isolated as a versioned preview and clearly labeled pre-release. - Movement on an upstream default branch cannot by itself change public rendered prose, published skill guidance, or released verification SHAs. diff --git a/planning/released-antd-v0.11.2-audit.md b/planning/released-antd-v0.11.2-audit.md index e4c2897..4237d47 100644 --- a/planning/released-antd-v0.11.2-audit.md +++ b/planning/released-antd-v0.11.2-audit.md @@ -129,14 +129,14 @@ All six defects are present at v0.11.2 source commit `3264b514...`. | 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 installable at SHA; no PyPI release | +| 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 installable at SHA; no crates.io package | +| 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`. Python and Rust can be installed from the exact Git source, but this is not a PyPI or crates.io release. 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. +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 @@ -173,7 +173,7 @@ The emergency branch changes 45 files relative to `origin/main` and was built ar | 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. | -| **Keep** | Language-binding overview and guides | Keep corrected package-identity/availability principle, source-pinned Python and Rust installs with prerequisites, and complete examples that were independently checked. | +| **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. | @@ -261,6 +261,6 @@ Canonical source URLs are linked in each findings section. Moving-head queries u - 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 installs are not public package releases. +- 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. From 5dbecd560861d07722702dac52f643aca8f685bd Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 14:29:52 +0100 Subject: [PATCH 06/26] docs(gsd): record ADR correction review --- planning/STATE.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 7c8cd27..36800f5 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,12 +4,12 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: remediate Proposed ADR-0016 review findings -- Status: code-review blockers; attended checkpoint +- Task: rerun Proposed ADR-0016 review after state correction +- Status: substantive corrections passed; code-review bookkeeping finding; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` -- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; remediation `735091d7ed55db90eb48129c879796dc6ebfe963` +- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -21,15 +21,15 @@ ## Review State -- Remediation commit `735091d` addresses the first 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. -- Structural validation after remediation: ADR governance passed with 1 ADR checked; 20 governance tests passed; `git diff --check origin/main...HEAD` passed; worktree was clean. -- Independent code review: `issues_found`. - - HIGH: the retained-incumbent rule can preserve a release that has itself become withdrawn, insecure, network-incompatible, or baseline-noncompliant. Retention must require the incumbent still to pass applicable safety and baseline requirements; otherwise guidance must narrow or state that no supported baseline exists. - - MEDIUM: the audit calls Python and Rust exact-source routes installable without clean-install commands/results. Add reproducible evidence or relabel them as identified but not runtime-verified. -- Goal verification, adversarial re-review, and Craft re-review have not run on remediation commit `735091d` because code review blocked advancement. +- 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. +- Independent code re-review: both substantive findings resolved; `issues_found` only because this state file still described the now-completed correction. This update corrects the handoff, but the code-review gate has not yet been rerun. +- Goal verification, adversarial re-review, and Craft re-review have not run on commit `57ec56c` because the code-review gate stopped on the stale-state finding. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: no remote branch/PR exists; local evidence is weaker and must not be called CI-green. +- 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 @@ -40,4 +40,4 @@ ## Next -- With Jim's attended approval, add the incumbent-disqualification invariant and correct the audit's Python/Rust installability evidence labels, then rerun code review, goal verification, adversarial, Craft, and the deferred clean-context gate before returning for the human acceptance decision. +- With Jim's attended approval, rerun code review now that the state record is accurate, then continue to goal verification, adversarial, Craft, and the deferred clean-context gate before returning for the human acceptance decision. From ff9761a1d8366775f61ccb44061922bcac560067 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 14:39:54 +0100 Subject: [PATCH 07/26] docs(gsd): prepare ADR acceptance checkpoint --- planning/STATE.md | 11 +-- planning/gsd-adr-0016-checkpoint.md | 121 ++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+), 5 deletions(-) create mode 100644 planning/gsd-adr-0016-checkpoint.md diff --git a/planning/STATE.md b/planning/STATE.md index 36800f5..82f5640 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: rerun Proposed ADR-0016 review after state correction -- Status: substantive corrections passed; code-review bookkeeping finding; attended checkpoint +- Task: complete Proposed ADR-0016 gauntlet reviews +- Status: code-reviewed and goal-verified; adversarial, Craft, and clean-context pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -24,8 +24,9 @@ - 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. -- Independent code re-review: both substantive findings resolved; `issues_found` only because this state file still described the now-completed correction. This update corrects the handoff, but the code-review gate has not yet been rerun. -- Goal verification, adversarial re-review, and Craft re-review have not run on commit `57ec56c` because the code-review gate stopped on the stale-state finding. +- 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, Craft re-review, and a fresh clean-context attempt remain pending. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: no remote branch/PR exists; local evidence is weaker and must not be called CI-green. @@ -40,4 +41,4 @@ ## Next -- With Jim's attended approval, rerun code review now that the state record is accurate, then continue to goal verification, adversarial, Craft, and the deferred clean-context gate before returning for the human acceptance decision. +- Run adversarial, Craft, and clean-context gates against the review-ready proposal and draft checkpoint, then return to Jim for the human acceptance decision. Do not begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md new file mode 100644 index 0000000..e12423f --- /dev/null +++ b/planning/gsd-adr-0016-checkpoint.md @@ -0,0 +1,121 @@ +# GSD Checkpoint — Proposed ADR-0016 review + +Date: 2026-08-20 +Project: Autonomi Developer Documentation +Slice/question: Should released truth replace moving merged truth as the default public documentation source? +Prepared by: orchestrator +Agents/tools used: operative, codereviewer, verifier; adversarial, Craft, and clean-context pending + +## Status + +Continue through remaining review gates; not yet ready for the human acceptance decision. + +Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. +Review cadence: per-unit in progress +Unreviewed backlog if deferred: none; remaining gates are pending for this unit + +## What happened + +Proposed ADR-0016 makes released, publicly obtainable, compatible, capability-evidenced truth the default for public rendered developer documentation and the published developer skill. It preserves moving default branches as next-release watch inputs, retains `target-manifest` for isolated pre-release previews, defines promotion and honest fallback evidence, and supersedes only the relevant portions of ADR-0003 and ADR-0004. + +The branch also carries the dated v0.11.2 motivating audit as inspectable evidence. The audit explicitly distinguishes historical policy from current authority, records evidence gaps, and notes that Python and Rust source-install routes were identified but not clean-install or runtime verified. + +No implementation, rendered documentation, skill, manifest, automation, CI, test, or Accepted ADR changed. ADR-0016 remains Proposed. + +## Evidence + +CI arbiter / green of record: + +- Location: none; no remote branch, PR, or repository CI workflow exists for this work-unit. +- Status: no CI arbiter exists; evidence is weaker. + +Local fast gate / `.gsd/gate.sh`: + +- Installed? N/A — the repository has no `.gsd/gate.sh`. +- Commands run: ADR governance, governance unit tests, and `git diff --check`. +- Result: passed. + +Files changed/artifacts produced: + +- `adr/ADR-0016-released-truth-for-public-developer-docs.md` +- `planning/released-antd-v0.11.2-audit.md` +- `planning/STATE.md` +- `planning/gsd-adr-0016-checkpoint.md` + +Checks run: + +- `python3 -I scripts/adr-governance.py` +- `python3 -I -m unittest discover -s scripts/tests -p 'test_adr_governance.py'` +- `git diff --check origin/main...HEAD` +- Independent code review of the complete diff. +- Goal-backward verification against the approved decision intent and Accepted ADR boundaries. + +Results: + +- ADR governance: passed, 1 ADR checked. +- Governance tests: 20 passed. +- Diff check: passed. +- Code review: passed, no findings. +- Goal verification: passed, 7/7 goals verified. +- Accepted ADRs: byte-identical to the base. + +## Honesty rules check + +- No-harness-modification: Pass + - No test, harness, daemon, build, environment, gate, or CI change. +- Baseline-diff for evidence: Pass + - No failure or skip was dismissed as environmental, flaky, or pre-existing. +- Evidence reproducible-from-branch: Pass + - The motivating audit and representative commands are committed on this branch; no uncommitted wrapper or environment variable is required. +- Local vs CI consistency: N/A — no CI arbiter exists; local evidence is explicitly weaker. + +## Ledger / forks + +Not applicable; attended run. No forks or split decisions were created. + +## Review findings + +Clean-context test: + +- Reviewer/tool: panel Claude lane +- Result: Not run for the corrected proposal +- Findings: a prior attempt was deferred because authentication was unavailable (`models: unavailable (auth) · 0s`); a fresh attempt remains pending. + +Adversarial review: + +- Reviewer/tool: adversarial +- Required? Yes — architecture and public documentation policy. +- Result: Not run on the corrected proposal +- If Not run: pending before the acceptance checkpoint. +- Findings: none yet. + +Craft Review: + +- Reviewer/tool: craft +- Required? Yes — repository-governance and maintainer-conformance work. +- Verdict: Not run on the corrected proposal +- If Not run: pending before the acceptance checkpoint. +- CONFORMANCE findings and dispositions: none yet. +- SIMPLICITY / NIT findings carried: none yet. + +## Drift / scope concerns + +The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and issue #233 has closed. A fresh candidate-release audit is required before implementation; ADR acceptance does not promote v0.11.2 or authorize documentation changes. + +## Open questions / decisions for Jim + +After the remaining review gates: accept, reject, or request changes to Proposed ADR-0016. + +PR / upstream action gate, if applicable: + +- PR ready to raise? No +- Jim confirmed PR may be opened? No +- Draft PR title/description prepared: No + +## Recommended next step + +Run adversarial, Craft, and clean-context gates. If they pass, return to Jim for the ADR acceptance decision. Do not begin implementation. + +## Handoff note + +The proposal is code-reviewed and goal-verified but is not Accepted and has not completed its gauntlet. No implementation is authorized. From 512d9dfef5a8465f71d159402a1b13217fcdb38f Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 14:49:50 +0100 Subject: [PATCH 08/26] docs(gsd): record ADR adversarial blockers --- planning/STATE.md | 19 +++++++--- planning/gsd-adr-0016-checkpoint.md | 54 ++++++++++++++++------------- 2 files changed, 44 insertions(+), 29 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 82f5640..f68796e 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: complete Proposed ADR-0016 gauntlet reviews -- Status: code-reviewed and goal-verified; adversarial, Craft, and clean-context pending +- Task: remediate Proposed ADR-0016 adversarial findings +- Status: adversarial NOT-READY; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -26,10 +26,19 @@ - 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, Craft re-review, and a fresh clean-context attempt remain pending. +- 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. +- Craft re-review and fresh clean-context were not run because the adversarial gate blocked advancement. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` -- CI arbiter: no remote branch/PR exists; local evidence is weaker and must not be called CI-green. +- CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. - 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 @@ -41,4 +50,4 @@ ## Next -- Run adversarial, Craft, and clean-context gates against the review-ready proposal and draft checkpoint, then return to Jim for the human acceptance decision. Do not begin implementation. +- With Jim's attended approval, remediate the adversarial policy, supersession, skill-parity, dependency-identity, and evidence-record findings; rerun code review and goal verification against the resulting HEAD; then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index e12423f..7094aba 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -4,19 +4,19 @@ Date: 2026-08-20 Project: Autonomi Developer Documentation Slice/question: Should released truth replace moving merged truth as the default public documentation source? Prepared by: orchestrator -Agents/tools used: operative, codereviewer, verifier; adversarial, Craft, and clean-context pending +Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and clean-context not run after adversarial blocker ## Status -Continue through remaining review gates; not yet ready for the human acceptance decision. +Revise — adversarial review returned NOT-READY. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit in progress -Unreviewed backlog if deferred: none; remaining gates are pending for this unit +Review cadence: per-unit blocked at adversarial review +Unreviewed backlog if deferred: Craft and clean-context are not run because adversarial blocked advancement ## What happened -Proposed ADR-0016 makes released, publicly obtainable, compatible, capability-evidenced truth the default for public rendered developer documentation and the published developer skill. It preserves moving default branches as next-release watch inputs, retains `target-manifest` for isolated pre-release previews, defines promotion and honest fallback evidence, and supersedes only the relevant portions of ADR-0003 and ADR-0004. +Proposed ADR-0016 makes released, publicly obtainable, compatible, capability-evidenced truth the default for public rendered developer documentation and the published developer skill. It preserves moving default branches as next-release watch inputs, retains `target-manifest` for isolated pre-release previews, and defines promotion and honest fallback evidence. It currently claims to supersede only portions of ADR-0003 and ADR-0004; adversarial review found that the proposal also conflicts with provenance-refresh invariants in ADR-0006 and ADR-0014 and affects ADR-0013. The branch also carries the dated v0.11.2 motivating audit as inspectable evidence. The audit explicitly distinguishes historical policy from current authority, records evidence gaps, and notes that Python and Rust source-install routes were identified but not clean-install or runtime verified. @@ -26,8 +26,8 @@ No implementation, rendered documentation, skill, manifest, automation, CI, test CI arbiter / green of record: -- Location: none; no remote branch, PR, or repository CI workflow exists for this work-unit. -- Status: no CI arbiter exists; evidence is weaker. +- Location: `.github/workflows/adr-governance.yml`, triggered by pull requests that change `adr/**`. +- Status: the CI arbiter exists, but no remote branch, pull request, or exact-SHA CI run exists. Local evidence is weaker and is not CI-green. Local fast gate / `.gsd/gate.sh`: @@ -47,16 +47,16 @@ Checks run: - `python3 -I scripts/adr-governance.py` - `python3 -I -m unittest discover -s scripts/tests -p 'test_adr_governance.py'` - `git diff --check origin/main...HEAD` -- Independent code review of the complete diff. -- Goal-backward verification against the approved decision intent and Accepted ADR boundaries. +- Independent code review through commit `5dbecd5`, before the later state/checkpoint-only commit. +- Goal-backward verification through commit `5dbecd5` against the approved decision intent and Accepted ADR boundaries. Results: - ADR governance: passed, 1 ADR checked. - Governance tests: 20 passed. - Diff check: passed. -- Code review: passed, no findings. -- Goal verification: passed, 7/7 goals verified. +- Code review through `5dbecd5`: passed, no findings; detailed reviewer output was session-local rather than a committed report. +- Goal verification through `5dbecd5`: passed, 7/7 goals verified; detailed verifier output was session-local rather than a committed report. - Accepted ADRs: byte-identical to the base. ## Honesty rules check @@ -65,9 +65,9 @@ Results: - No test, harness, daemon, build, environment, gate, or CI change. - Baseline-diff for evidence: Pass - No failure or skip was dismissed as environmental, flaky, or pre-existing. -- Evidence reproducible-from-branch: Pass - - The motivating audit and representative commands are committed on this branch; no uncommitted wrapper or environment variable is required. -- Local vs CI consistency: N/A — no CI arbiter exists; local evidence is explicitly weaker. +- Evidence reproducible-from-branch: Concern + - The motivating audit and representative commands are committed and require no uncommitted wrapper or environment variable. Detailed code-review and verifier reports were session-local and must be persisted or their claims narrowed before readiness. +- Local vs CI consistency: no conflict observed, but the applicable CI arbiter has not run. ## Ledger / forks @@ -79,22 +79,28 @@ Clean-context test: - Reviewer/tool: panel Claude lane - Result: Not run for the corrected proposal -- Findings: a prior attempt was deferred because authentication was unavailable (`models: unavailable (auth) · 0s`); a fresh attempt remains pending. +- Findings: a prior attempt was deferred because authentication was unavailable (`models: unavailable (auth) · 0s`); no fresh attempt ran because adversarial review blocked advancement. Adversarial review: -- Reviewer/tool: adversarial +- Reviewer/tool: adversarial — OpenAI GPT-5.6-sol; implementer provider unrecorded, so cross-provider independence is unconfirmed - Required? Yes — architecture and public documentation policy. -- Result: Not run on the corrected proposal -- If Not run: pending before the acceptance checkpoint. -- Findings: none yet. +- Result: Blockers +- Findings: + - HIGH: candidate eligibility must explicitly require stable/general-availability status and symmetric candidate safety/security qualification. + - HIGH: deterministic newest-candidate discovery/ordering and continuing incumbent requalification are missing. + - HIGH: supersession conflicts with ADR-0006 and ADR-0014, with an ADR-0013 stamp-refresh impact. + - HIGH: applicable PR-triggered ADR Governance CI exists but has not run. + - MEDIUM: skill parity is ambiguous under the pointer-based skill model. + - MEDIUM: distributable release identity and transitive dependency identity are conflated. + - MEDIUM: review/verification evidence and exact reviewed SHA were overstated. Craft Review: - Reviewer/tool: craft - Required? Yes — repository-governance and maintainer-conformance work. -- Verdict: Not run on the corrected proposal -- If Not run: pending before the acceptance checkpoint. +- Verdict: Not run +- If Not run: adversarial NOT-READY blocked advancement; rerun after remediation. - CONFORMANCE findings and dispositions: none yet. - SIMPLICITY / NIT findings carried: none yet. @@ -104,7 +110,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -After the remaining review gates: accept, reject, or request changes to Proposed ADR-0016. +Approve or decline remediation of the adversarial findings. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -114,8 +120,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run adversarial, Craft, and clean-context gates. If they pass, return to Jim for the ADR acceptance decision. Do not begin implementation. +Revise the proposal and evidence record, rerun code review and goal verification against the resulting HEAD, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -The proposal is code-reviewed and goal-verified but is not Accepted and has not completed its gauntlet. No implementation is authorized. +The proposal passed code review and goal verification at `5dbecd5`, but adversarial review of `ff9761a` returned NOT-READY. It is not acceptance-ready, Craft and clean-context have not run, CI has not run, and no implementation is authorized. From fb67648a8ac0a874ea94a1e1c3e208490a052a8c Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:17:23 +0100 Subject: [PATCH 09/26] docs(adr): clarify released-truth lifecycle - Define stable candidate eligibility, deterministic ordering, and symmetric requalification - Bound supersession, skill parity, release identity, and validation invariants --- ...eleased-truth-for-public-developer-docs.md | 68 ++++++++++++++++--- 1 file changed, 59 insertions(+), 9 deletions(-) diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md index b80ee8b..69fb13d 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -5,7 +5,7 @@ - **Date:** 2026-08-12 - **Decision owners:** Jim Collinson - **Reviewers:** Jim Collinson -- **Supersedes:** ADR-0003 (source-selection default and verification-mode set only); ADR-0004 (source resolution and drift semantics for the default public surface only) +- **Supersedes:** ADR-0003 (public source-selection default, verification-mode set, and HEAD-based freshness semantics for default public docs and skill only); ADR-0004 (default-public source resolution, staleness detection, and provenance-advance semantics only); ADR-0006 (conditions under which metadata-only provenance may advance for default public artifacts only); ADR-0013 (default-branch stamp-refresh interpretation for published-skill provenance only); ADR-0014 (source and conditions for pure public-skill provenance refresh only) - **Superseded by:** none - **Related:** ADR-0005 through ADR-0007; ADR-0012 through ADR-0014; `planning/verification-workflow.md`; `planning/implementation-plan.md` §5; `planning/released-antd-v0.11.2-audit.md`; [WithAutonomi/ant-sdk issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233) @@ -42,25 +42,50 @@ The existing `target-manifest` mode can pin a release-hardening pass, but ADR-00 Public rendered developer documentation and the published developer skill will describe **released truth** by default: the newest coherent release set that passes the mandatory public-baseline evidence below. The release set must be publicly obtainable through documented standard routes, compatible with its shipped dependencies and the deployed Autonomi Network for the claims made, and supported by capability-specific evidence. +### Verification modes and authorities + The verification model will retain exact per-surface provenance while changing its default: -- **`released-truth` is the default mode for public rendered documentation and the published developer skill.** Verification resolves every documented surface to exact refs in one machine-readable release manifest. A ref may identify a component's own release or the exact dependency ref shipped by another released product. +- **`released-truth` is the default mode for public rendered documentation and the published developer skill.** Verification resolves every documented surface to exact refs in one machine-readable active released-truth manifest. - **The release manifest represents a coherent product set, not a bag of latest tags.** Component versions, transitive refs that carry documented behavior, and deployed Autonomi Network compatibility must agree for the claims that depend on them. +- **The active released-truth manifest is the sole mutable machine-readable authority for active public release identities and capability support statuses.** Each promotion leaves an immutable promotion record as the evidence for why that manifest state was selected. Verification records and skill metadata identify the exact sources audited for their surfaces, but do not independently select a different active release or support status. - **`target-manifest` remains an explicit pre-release, launch-hardening, or release-candidate mode.** It does not become the current public developer surface before release. If target content is published, it must be isolated and clearly labeled as a versioned preview rather than replacing the default docs. - **`current-merged-truth` is retired as a verification mode for public rendered documentation and the published skill.** Moving default branches remain research inputs for drift detection, impact assessment, and next-release preparation. A merge can open an audit queue; it cannot silently advance rendered prose or verification SHAs. +### Release identities and candidate eligibility + +An independently obtainable component is eligible for a `released-truth` candidate only through a stable or general-availability public distributable release identity published by its canonical publisher. That identity records its stable or general-availability publication state and canonical release URL or registry identity, immutable source identity, published artifacts and checksums where artifacts are distributed, and standard installation identity. Drafts; alpha, beta, release-candidate (RC), preview, nightly, canary, or equivalent prereleases; branch builds; and mutable aliases without an immutable underlying release identity are ineligible. They may appear only in isolated `target-manifest` preview mode. + +A transitive shipped dependency has a different identity contract. It records the exact locked ref and an inspectable dependency path from the parent distributable release. It needs its own stable or general-availability release URL only when the public guidance presents it as independently obtainable. A transitive ref proves what a parent release shipped; it never by itself establishes that the dependency is independently installable or eligible as a released-truth candidate. + +### Deterministic lifecycle and symmetric qualification + +Candidate discovery reads canonical stable or general-availability publication state, independently of default-branch movement and prior watch-state observations. A stable release remains discoverable even when its source commit was already observed on a default branch before publication. + +Eligible coherent release sets are ordered by a deterministic component-wise partial order. One set dominates another only when it is not older for every component under the component's immutable canonical release ordering and is newer for at least one component. Every maximal non-dominated eligible set is considered. When maximal sets are incomparable, selection uses a committed, predeclared, reviewed total extension with a fixed component-identity order and immutable release-identity tie-breakers. The result must not depend on HEAD, API or filesystem result order, audit time, or evidence-completion order. Exact release-order extraction and comparator mechanics belong in the later specification. + +Candidate and incumbent qualification is symmetric. Both must independently pass applicable obtainability, provenance-integrity, safety and security, deployed-network identity and compatibility, and mandatory public-baseline requirements. Promotion is not permanent: the incumbent is requalified during every promotion decision and whenever artifact availability or withdrawal, applicable safety or security evidence, or deployed-network identity or compatibility changes, even when there is no new candidate. Default-branch movement alone neither qualifies nor disqualifies a candidate or incumbent. + +Artifact-wide disqualifiers and capability-local defects have different scope. Withdrawal or unobtainability, failed provenance integrity, an artifact-wide safety or security failure, or incompatible deployed-network behavior disqualifies the artifact for every affected journey. A defect confined to a non-baseline capability may leave the rest of a qualified release set active when the affected capability is classified honestly and its remaining guidance is safe. If safety or security evidence does not establish whether a defect is artifact-wide or capability-local, qualification fails closed for every plausibly affected journey until the scope is established. + +If no eligible candidate qualifies and no incumbent remains qualified, the public surface must not fall back to moving source, a prerelease, or an old artifact that has not been evaluated under the active baseline. Affected guidance is narrowed or withdrawn and states that no supported baseline exists. + +### Promotion evidence + Every candidate release set requires a committed, machine-readable release manifest and an inspectable promotion record. Promotion fails closed if any mandatory field or evidence is absent. The record must contain, at minimum: -- **Immutable release identity:** the public version and release URL for each component, immutable tag object and peeled source commit where applicable, exact shipped dependency refs, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable. +- **Immutable release identity:** the public stable or general-availability distributable identity for every independently obtainable component, including canonical publication state and URL or registry identity, immutable tag object and peeled source commit where applicable, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable; plus the exact locked ref and inspectable parent path for each transitive shipped dependency that carries documented behavior. - **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. - **Release-set compatibility and deployed-network identity:** locked dependency evidence for the shipped set and, for network-dependent claims, the network environment, observation date, protocol or configuration anchor, and the most precise inspectable deployment identity available. If the deployed state cannot be identified precisely enough to reproduce a claim, that claim remains unverified and cannot be promoted. - **Capability and runtime evidence:** a matrix mapping each public interface, capability, and material operation to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. - **Known limitations and alternatives:** known defects, affected versions and operations, upstream issue links for material defects, and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when the supported usage remains safe and reproducible; otherwise the capability is `unavailable` or `deferred`. -- **Cross-surface consistency:** the public docs and published developer skill must map every covered interface and capability to the same support status, known defect or limitation, and safe alternative. Matching refs alone is insufficient. A mismatch blocks promotion. +- **Cross-surface consistency:** the public docs and published developer skill must map the enumerable coverage set defined below to the same support status, known defect or limitation, and safe alternative. Matching refs alone is insufficient. A mismatch blocks promotion. - **Objective supported-baseline retention:** the incumbent supported release set, the candidate release set, each result against the predeclared mandatory public baseline, and the resulting promote-or-retain outcome. A candidate replaces the incumbent only when every mandatory promotion requirement passes. If any requirement fails, the incumbent remains the supported default only for journeys where it continues to satisfy applicable obtainability, safety and security, deployed-network compatibility, and mandatory baseline requirements. A withdrawn or unobtainable, unsafe or insecure, incompatible, or baseline-noncompliant incumbent is disqualified for the affected journey. If no qualifying incumbent exists, the candidate remains unpromoted, affected guidance is narrowed or withdrawn, and public guidance explicitly states that no supported baseline exists for that journey until a released candidate passes. The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. Subject to the incumbent qualification rule above, the prior supported release set remains the default until a candidate passes every promotion requirement. When a newer available release is unsuitable and the incumbent remains qualified, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command; retaining an older baseline through stale metadata or omission is prohibited. When the incumbent is disqualified, the affected guidance must instead narrow or withdraw the journey and state that no supported baseline exists until a released candidate passes. +### Capability truth and skill parity + Released truth is capability-specific and evidence-based: - “Usable” does not mean “bug-free.” A known defect is part of released truth. The docs must state the affected route, boundary, or operation and provide a safe alternative when one exists. @@ -69,6 +94,10 @@ Released truth is capability-specific and evidence-based: - A release is promoted into public docs only when its manifest and promotion record satisfy the mandatory fields and evidence floors in this decision. - Non-baseline capabilities do not block the whole release set when their status and guidance are honest. They remain `unavailable` or `deferred`, or `supported-with-known-limitation` when a safe, verified usage boundary exists. +The active manifest defines an enumerable coverage set of stable interface, capability, and material-operation identifiers. It covers every claim represented in the rendered docs and everything the published skill bundles, recommends, warns about, or routes through a pointer. + +For each covered identifier, the skill may represent released guidance as bundled content or as an explicit pointer to the default released-truth docs. A pointer satisfies parity only when it resolves under the same active manifest, the skill carries no contradictory claim, and the agent fetches the released guidance before answering release-sensitive detail. If that fetch fails, the agent defers the release-sensitive detail instead of consulting moving source or fabricating an answer. Parity does not require duplication of pointered prose. Any claim, recommendation, warning, limitation, alternative, or routing instruction that the skill does bundle must match the active released guidance directly. + The existing verification-block invariants remain: - Every rendered documentation surface carries one or more machine-readable verification records with source repository, ref, exact commit SHA, verification date, and verification mode. @@ -76,7 +105,19 @@ The existing verification-block invariants remain: - A surface presented as verified never uses `source_commit: TBD`. - Provenance mechanics remain outside rendered prose, while released defects, limitations, and safe alternatives appear in rendered guidance when developers need them. -ADR-0004 continues to govern deterministic detection, fail-closed behavior, and model-tiered auditing, but this ADR supersedes its source-resolution and drift semantics for the default public surface. Released-record conformance and next-release source movement are separate detector outcomes. A released-truth record resolves through the active release manifest, not through the repository registry plus a GitHub default branch; deterministic comparison against that manifest detects corruption or inconsistency in released records. Default branches remain registry-resolved watch inputs and are compared with a separately tracked, last-audited watch state. Their movement creates next-release impact candidates, but does not mark released records stale, authorize a metadata re-stamp, or advance released provenance. Completing a next-release impact audit may advance the watch state without changing the released record. Metadata-only and prose audit tiers remain, but public SHAs change only through release promotion. ADR-0005 through ADR-0007 continue to govern scheduling, update-track separation, and fail-closed operation. Detailed manifest and watch-state schemas, promotion and detection mechanics, migration sequencing, and automation changes belong in a follow-up specification and plan. +Released-record conformance and next-release source movement are separate detector outcomes. A released-truth record resolves through the active release manifest, not through the repository registry plus a GitHub default branch; deterministic comparison against that manifest detects corruption or inconsistency in released records. Default branches remain registry-resolved watch inputs and are compared with a separately tracked, last-audited watch state. Their movement creates next-release impact candidates, but does not mark released records stale, authorize a metadata re-stamp, or advance released provenance. Completing a next-release impact audit may advance the watch state without changing the released record. + +### Supersession scope and preserved invariants + +This ADR supersedes only the named default-public source and provenance-advance semantics in Accepted ADRs: + +- **ADR-0003:** superseded for the public source-selection default, verification-mode set, and HEAD-based freshness semantics of default public rendered docs and the published skill. Its exact provenance schema, exact-SHA requirement, no-placeholder rule, provenance/body separation, and explicit target pinning remain intact. +- **ADR-0004:** superseded for default-public source resolution, staleness detection, and provenance-advance semantics. Its deterministic, model-free, fail-closed detection; candidate-not-directive rule; and efficient-model versus frontier-model audit tiers remain intact. +- **ADR-0006:** superseded only for the conditions under which metadata-only provenance may advance for default public artifacts. Its two mutually exclusive tracks, mechanical change envelopes, stronger prose review, reachability checks, and coherent skill-state requirement remain intact. Under `released-truth`, metadata-only public provenance advances only to refs authorized by promotion into the active manifest, never merely because HEAD moved. +- **ADR-0013:** superseded only for the default-branch stamp-refresh interpretation of published-skill provenance. Its three-part freshness defense, pointer content tier, runtime version check, and stable-URL contract remain intact. A skill stamp refresh now means conformance to the active released-truth manifest, not conformance to moving HEAD. +- **ADR-0014:** superseded only for the source and conditions of a pure public-skill provenance refresh. Its shared source-audit workflow, `feeds_skills` relationship, distinct metadata responsibilities, and coherent-state requirement remain intact. Pure skill provenance may advance only with a released-truth promotion. The content version and release history may remain unchanged only when bundled claims, recommendations, warnings, limitations, alternatives, and pointers remain unchanged. + +ADR-0005 and ADR-0007 remain fully intact. Scheduling, adapters, detailed manifest and watch-state schemas, exact comparator mechanics, promotion and detection mechanics, migration sequencing, and automation changes belong in a follow-up specification and plan. ## Consequences @@ -92,7 +133,7 @@ ADR-0004 continues to govern deterministic detection, fail-closed behavior, and - Documentation can intentionally lag merged source until a release is promoted. - Maintaining a coherent manifest across multiple repositories and deployed-network dependencies adds release-management work. -- If release promotion is neglected, public docs can become stale even while drift detection is working. +- If promotion or incumbent requalification is neglected, public docs can become stale even while source-movement detection is working. - Capability-specific evidence and known-defect guidance require continuing judgment and maintenance. - Some source-present bindings or APIs will remain undocumented as supported until an obtainable, verified route exists. @@ -100,20 +141,29 @@ ADR-0004 continues to govern deterministic detection, fail-closed behavior, and - Default-branch movement still matters: it starts impact assessment and prepares future documentation, but does not itself change released truth. - Versioned previews may describe a target release when clearly separated from the default public docs. -- Accepted ADR-0003 remains immutable; this ADR's `Supersedes` field is the authoritative supersession link if this proposal is accepted. -- The exact release-manifest shape, migration from existing modes, release-promotion workflow, and automation updates require a separate reviewed specification and execution plan. +- Accepted ADRs remain immutable; this ADR's `Supersedes` field is the authoritative supersession link if this proposal is accepted. +- The exact release-manifest shape, comparator, migration from existing modes, release-promotion workflow, and automation updates require a separate reviewed specification and execution plan. ## Validation This decision is satisfied when all of the following remain true: - Every public installation or package identity resolves through its documented supported route from a clean environment. +- Candidate discovery rejects drafts, prereleases of every named class, branch builds, and mutable aliases without immutable release identity; those identities can appear only in isolated target previews. +- A stable or general-availability release remains discoverable from canonical publication state when its source commit was already observed on HEAD before publication. +- Shuffling API, registry, or filesystem discovery results does not change the eligible sets, maximal non-dominated sets, precedence, or promotion outcome. +- Incomparable maximal release sets resolve identically through the committed total extension and its fixed component order and immutable release-identity tie-breakers. - Every public verification record resolves to exact refs in one coherent release manifest, including shipped dependency refs where they carry documented behavior. - Every release promotion record contains all seven minimum evidence groups required by this decision and identifies the predeclared mandatory public baseline. +- Candidate and incumbent qualification apply the same obtainability, provenance-integrity, safety and security, deployed-network compatibility, and mandatory-baseline requirements. +- Artifact withdrawal or loss, applicable advisory or safety evidence, and deployed-network identity or compatibility change requalify the incumbent without requiring a new candidate. - Claims that depend on deployed Autonomi Network behavior are checked against the identified compatible deployed state; claims without a reproducible deployment anchor remain unverified. - Getting-started and how-to journeys have complete runtime evidence for the released interface they recommend; source or schema inspection alone does not pass. - Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. -- Every covered capability has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. +- A capability-local non-baseline defect changes only its covered capability when evidence establishes that isolation; uncertain safety or security scope fails closed for every plausibly affected journey. +- Every coverage-set identifier has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. +- Pointer parity resolves against the active released-truth manifest, fetches released guidance before release-sensitive answers, and defers that detail on fetch failure; bundled skill guidance matches directly without requiring duplicated pointer prose. +- A transitive dependency ref with no independent release URL remains valid shipped-dependency provenance but does not establish independent installability or candidate eligibility. - If a newer available release fails the mandatory baseline and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command. - If an incumbent becomes withdrawn or unobtainable, unsafe or insecure, incompatible with the deployed Autonomi Network, or noncompliant with the mandatory baseline, affected guidance narrows or withdraws the journey and states that no supported baseline exists until a released candidate passes. - No verification record backing the default public rendered documentation or published developer skill uses `current-merged-truth`. From e3df50957d2691b8661c503bfd6f34cc960aece9 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:18:48 +0100 Subject: [PATCH 10/26] docs(gsd): record ADR adversarial remediation --- planning/STATE.md | 12 +++++++----- planning/gsd-adr-0016-checkpoint.md | 27 ++++++++++++++------------- 2 files changed, 21 insertions(+), 18 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index f68796e..ca22ae5 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,12 +4,12 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: remediate Proposed ADR-0016 adversarial findings -- Status: adversarial NOT-READY; attended checkpoint +- Task: re-review Proposed ADR-0016 after adversarial remediation +- Status: adversarial findings remediated; code review and verification pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` -- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87` +- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -35,7 +35,9 @@ - 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. -- Craft re-review and fresh clean-context were not run because the adversarial gate blocked advancement. +- 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. +- Code review and goal verification have not yet run against the remediated content. Craft re-review and fresh clean-context remain blocked until adversarial passes. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -50,4 +52,4 @@ ## Next -- With Jim's attended approval, remediate the adversarial policy, supersession, skill-parity, dependency-identity, and evidence-record findings; rerun code review and goal verification against the resulting HEAD; then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- Rerun code review and goal verification against the remediated branch and persist exact-SHA evidence, then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 7094aba..15847b8 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,15 +8,15 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Revise — adversarial review returned NOT-READY. +Continue — previous adversarial findings are remediated at `fb67648`; re-review is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit blocked at adversarial review -Unreviewed backlog if deferred: Craft and clean-context are not run because adversarial blocked advancement +Review cadence: per-unit re-review in progress +Unreviewed backlog if deferred: Craft and clean-context remain unrun until adversarial passes ## What happened -Proposed ADR-0016 makes released, publicly obtainable, compatible, capability-evidenced truth the default for public rendered developer documentation and the published developer skill. It preserves moving default branches as next-release watch inputs, retains `target-manifest` for isolated pre-release previews, and defines promotion and honest fallback evidence. It currently claims to supersede only portions of ADR-0003 and ADR-0004; adversarial review found that the proposal also conflicts with provenance-refresh invariants in ADR-0006 and ADR-0014 and affects ADR-0013. +Proposed ADR-0016 makes released, publicly obtainable, compatible, capability-evidenced truth the default for public rendered developer documentation and the published developer skill. It preserves moving default branches as next-release watch inputs, retains `target-manifest` for isolated pre-release previews, and defines promotion and honest fallback evidence. Remediation commit `fb67648` adds stable/general-availability candidate rules, symmetric candidate/incumbent safety, deterministic release-set discovery and ordering, continuing incumbent requalification, pointer-compatible skill parity, separate distributable/dependency identities, and precise partial supersession of ADR-0003, ADR-0004, ADR-0006, ADR-0013, and ADR-0014. The branch also carries the dated v0.11.2 motivating audit as inspectable evidence. The audit explicitly distinguishes historical policy from current authority, records evidence gaps, and notes that Python and Rust source-install routes were identified but not clean-install or runtime verified. @@ -58,6 +58,7 @@ Results: - Code review through `5dbecd5`: passed, no findings; detailed reviewer output was session-local rather than a committed report. - Goal verification through `5dbecd5`: passed, 7/7 goals verified; detailed verifier output was session-local rather than a committed report. - Accepted ADRs: byte-identical to the base. +- Adversarial-remediation local validation at `fb67648`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. ## Honesty rules check @@ -87,13 +88,13 @@ Adversarial review: - Required? Yes — architecture and public documentation policy. - Result: Blockers - Findings: - - HIGH: candidate eligibility must explicitly require stable/general-availability status and symmetric candidate safety/security qualification. - - HIGH: deterministic newest-candidate discovery/ordering and continuing incumbent requalification are missing. - - HIGH: supersession conflicts with ADR-0006 and ADR-0014, with an ADR-0013 stamp-refresh impact. + - HIGH: candidate eligibility must explicitly require stable/general-availability status and symmetric candidate safety/security qualification. Remediated at `fb67648`; re-review pending. + - HIGH: deterministic newest-candidate discovery/ordering and continuing incumbent requalification are missing. Remediated at `fb67648`; re-review pending. + - HIGH: supersession conflicts with ADR-0006 and ADR-0014, with an ADR-0013 stamp-refresh impact. Remediated at `fb67648`; re-review pending. - HIGH: applicable PR-triggered ADR Governance CI exists but has not run. - - MEDIUM: skill parity is ambiguous under the pointer-based skill model. - - MEDIUM: distributable release identity and transitive dependency identity are conflated. - - MEDIUM: review/verification evidence and exact reviewed SHA were overstated. + - MEDIUM: skill parity is ambiguous under the pointer-based skill model. Remediated at `fb67648`; re-review pending. + - MEDIUM: distributable release identity and transitive dependency identity are conflated. Remediated at `fb67648`; re-review pending. + - MEDIUM: review/verification evidence and exact reviewed SHA were overstated. Claims remain narrowed; exact-SHA re-review evidence is pending. Craft Review: @@ -110,7 +111,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -Approve or decline remediation of the adversarial findings. ADR acceptance is not yet ready for decision. +No owner decision is pending until the remediated proposal completes re-review. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -120,8 +121,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Revise the proposal and evidence record, rerun code review and goal verification against the resulting HEAD, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Rerun code review and goal verification against the remediated branch, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -The proposal passed code review and goal verification at `5dbecd5`, but adversarial review of `ff9761a` returned NOT-READY. It is not acceptance-ready, Craft and clean-context have not run, CI has not run, and no implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. The policy findings are remediated in the content commit `fb67648`, but that commit has not yet passed independent re-review. The proposal is not acceptance-ready, Craft and clean-context have not run, CI has not run, and no implementation is authorized. From 81ed595a304f3d42e149382219288a0fde38d05c Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:25:58 +0100 Subject: [PATCH 11/26] docs(gsd): record ADR lifecycle review gaps --- planning/STATE.md | 12 ++++-- planning/adr-0016-code-review-e3df509.md | 52 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 25 +++++++++--- 3 files changed, 79 insertions(+), 10 deletions(-) create mode 100644 planning/adr-0016-code-review-e3df509.md diff --git a/planning/STATE.md b/planning/STATE.md index ca22ae5..be1c5e8 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: re-review Proposed ADR-0016 after adversarial remediation -- Status: adversarial findings remediated; code review and verification pending +- Task: remediate Proposed ADR-0016 lifecycle edge cases +- Status: code-review issues; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -37,7 +37,11 @@ - 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. -- Code review and goal verification have not yet run against the remediated content. Craft re-review and fresh clean-context remain blocked until adversarial passes. +- 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. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -52,4 +56,4 @@ ## Next -- Rerun code review and goal verification against the remediated branch and persist exact-SHA evidence, then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- With Jim's attended approval, define deterministic qualified-set fallback, requalify on every qualification-input change, and close mutable-alias drift; then rerun code review and goal verification before adversarial, Craft, and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 15847b8..6ad9fa9 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,10 +8,10 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — previous adversarial findings are remediated at `fb67648`; re-review is pending. +Revise — independent code review of the adversarial remediation found two HIGH lifecycle gaps and one MEDIUM alias gap. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit re-review in progress +Review cadence: per-unit blocked at code review Unreviewed backlog if deferred: Craft and clean-context remain unrun until adversarial passes ## What happened @@ -41,6 +41,7 @@ Files changed/artifacts produced: - `planning/released-antd-v0.11.2-audit.md` - `planning/STATE.md` - `planning/gsd-adr-0016-checkpoint.md` +- `planning/adr-0016-code-review-e3df509.md` Checks run: @@ -59,6 +60,7 @@ Results: - Goal verification through `5dbecd5`: passed, 7/7 goals verified; detailed verifier output was session-local rather than a committed report. - Accepted ADRs: byte-identical to the base. - Adversarial-remediation local validation at `fb67648`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. +- Code review at exact commit `e3df50957d2691b8661c503bfd6f34cc960aece9`: `issues_found`; two HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-e3df509.md`. ## Honesty rules check @@ -67,7 +69,7 @@ Results: - Baseline-diff for evidence: Pass - No failure or skip was dismissed as environmental, flaky, or pre-existing. - Evidence reproducible-from-branch: Concern - - The motivating audit and representative commands are committed and require no uncommitted wrapper or environment variable. Detailed code-review and verifier reports were session-local and must be persisted or their claims narrowed before readiness. + - The motivating audit, representative commands, and latest exact-SHA code-review report are committed and require no uncommitted wrapper or environment variable. The earlier verifier report was session-local; a new exact-SHA verification remains pending after remediation. - Local vs CI consistency: no conflict observed, but the applicable CI arbiter has not run. ## Ledger / forks @@ -76,6 +78,17 @@ Not applicable; attended run. No forks or split decisions were created. ## Review findings +Independent code review: + +- Reviewer/tool: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Reviewed commit: `e3df50957d2691b8661c503bfd6f34cc960aece9` +- Result: Issues found +- Findings: + - HIGH: define deterministic behavior when maximal eligible sets fail but a dominated older eligible set might qualify. + - HIGH: incumbent requalification must trigger whenever any qualification input changes, not only availability, security, or network evidence. + - MEDIUM: default install routes must pin immutable versions/digests or alias-target movement must trigger requalification. +- Report: `planning/adr-0016-code-review-e3df509.md` + Clean-context test: - Reviewer/tool: panel Claude lane @@ -111,7 +124,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until the remediated proposal completes re-review. ADR acceptance is not yet ready for decision. +Approve or decline remediation of the new lifecycle findings. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -121,8 +134,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Rerun code review and goal verification against the remediated branch, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Define deterministic qualified-set fallback, trigger requalification on every qualification-input change, and close mutable-alias drift. Then rerun code review and goal verification against the resulting content commit before adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. The policy findings are remediated in the content commit `fb67648`, but that commit has not yet passed independent re-review. The proposal is not acceptance-ready, Craft and clean-context have not run, CI has not run, and no implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`, but code review of `e3df509` found three remaining lifecycle edge cases. The proposal is not acceptance-ready, goal verification/adversarial re-review/Craft/clean-context have not run, CI has not run, and no implementation is authorized. From 9c2f1da15de685e54fdb0ef8eceeedfa2692f153 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:43:31 +0100 Subject: [PATCH 12/26] docs(adr): close released-truth lifecycle gaps - Define deterministic fallback and complete incumbent requalification triggers - Pin authoritative installs and constrain mutable aliases --- ...eleased-truth-for-public-developer-docs.md | 35 +++++++++++-------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md index 69fb13d..49cda87 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -54,7 +54,7 @@ The verification model will retain exact per-surface provenance while changing i ### Release identities and candidate eligibility -An independently obtainable component is eligible for a `released-truth` candidate only through a stable or general-availability public distributable release identity published by its canonical publisher. That identity records its stable or general-availability publication state and canonical release URL or registry identity, immutable source identity, published artifacts and checksums where artifacts are distributed, and standard installation identity. Drafts; alpha, beta, release-candidate (RC), preview, nightly, canary, or equivalent prereleases; branch builds; and mutable aliases without an immutable underlying release identity are ineligible. They may appear only in isolated `target-manifest` preview mode. +An independently obtainable component is eligible for a `released-truth` candidate only through a stable or general-availability public distributable release identity published by its canonical publisher. That identity records its stable or general-availability publication state and canonical release URL or registry identity, immutable source identity, published artifacts and checksums where artifacts are distributed, and standard installation identity. Drafts; alpha, beta, release-candidate (RC), preview, nightly, canary, or equivalent prereleases; and branch builds are ineligible. A mutable installation alias is not a release identity and cannot establish candidate eligibility or support. Default and recommended public install commands must resolve through immutable version or digest selectors. These ineligible identities may appear only in isolated `target-manifest` preview mode, except that a mutable alias may also appear as the non-authoritative convenience described under promotion evidence. A transitive shipped dependency has a different identity contract. It records the exact locked ref and an inspectable dependency path from the parent distributable release. It needs its own stable or general-availability release URL only when the public guidance presents it as independently obtainable. A transitive ref proves what a parent release shipped; it never by itself establishes that the dependency is independently installable or eligible as a released-truth candidate. @@ -62,27 +62,31 @@ A transitive shipped dependency has a different identity contract. It records th Candidate discovery reads canonical stable or general-availability publication state, independently of default-branch movement and prior watch-state observations. A stable release remains discoverable even when its source commit was already observed on a default branch before publication. -Eligible coherent release sets are ordered by a deterministic component-wise partial order. One set dominates another only when it is not older for every component under the component's immutable canonical release ordering and is newer for at least one component. Every maximal non-dominated eligible set is considered. When maximal sets are incomparable, selection uses a committed, predeclared, reviewed total extension with a fixed component-identity order and immutable release-identity tie-breakers. The result must not depend on HEAD, API or filesystem result order, audit time, or evidence-completion order. Exact release-order extraction and comparator mechanics belong in the later specification. +Eligible coherent release sets are ordered by a deterministic component-wise partial order. One set dominates another only when it is not older for every component under the component's immutable canonical release ordering and is newer for at least one component. A committed, predeclared, reviewed total extension with a fixed component-identity order and immutable release-identity tie-breakers extends that partial order across **all** eligible coherent release sets, not only the maximal non-dominated sets, and produces one newest-first candidate order. The incumbent is placed in that same order by its immutable release identities as the current baseline, including when changed inputs will disqualify it. Every promotion or requalification decision evaluates the ordered candidates and incumbent against all applicable qualification and promotion requirements and selects the first qualifying set. A failed maximal set does not stop evaluation: evaluation continues through the remaining maximal sets and then through older or dominated eligible sets until one qualifies or the sequence is exhausted. -Candidate and incumbent qualification is symmetric. Both must independently pass applicable obtainability, provenance-integrity, safety and security, deployed-network identity and compatibility, and mandatory public-baseline requirements. Promotion is not permanent: the incumbent is requalified during every promotion decision and whenever artifact availability or withdrawal, applicable safety or security evidence, or deployed-network identity or compatibility changes, even when there is no new candidate. Default-branch movement alone neither qualifies nor disqualifies a candidate or incumbent. +The existing incumbent participates in every decision as the current baseline and is requalified against the same inputs as the candidates. If it remains qualified, it is the first qualifying set unless a candidate that is strictly preferred under the committed total extension qualifies before it; a candidate at the same or a lower position cannot replace it. If the incumbent is disqualified, ordered evaluation continues until the first qualifying eligible set, including a set older than the former incumbent, is found. The selected set becomes the incumbent for later decisions, so a qualified incumbent cannot be displaced by an equally or less-preferred set and the fallback cannot create a downgrade loop. -Artifact-wide disqualifiers and capability-local defects have different scope. Withdrawal or unobtainability, failed provenance integrity, an artifact-wide safety or security failure, or incompatible deployed-network behavior disqualifies the artifact for every affected journey. A defect confined to a non-baseline capability may leave the rest of a qualified release set active when the affected capability is classified honestly and its remaining guidance is safe. If safety or security evidence does not establish whether a defect is artifact-wide or capability-local, qualification fails closed for every plausibly affected journey until the scope is established. +Candidate and incumbent qualification is symmetric. Both must independently pass applicable obtainability, provenance-integrity, safety and security, deployed-network identity and compatibility, and mandatory public-baseline requirements. A decision uses one committed snapshot of qualification inputs; discovery order, audit scheduling, and evidence-completion order cannot reorder evaluation or choose the result. Missing mandatory evidence fails qualification for that decision. Exact snapshot, enumeration, and comparator mechanics belong in the later specification. -If no eligible candidate qualifies and no incumbent remains qualified, the public surface must not fall back to moving source, a prerelease, or an old artifact that has not been evaluated under the active baseline. Affected guidance is narrowed or withdrawn and states that no supported baseline exists. +Promotion is not permanent. The incumbent is requalified during every promotion decision and whenever **any** qualification input changes, even when there is no new candidate. Triggers include artifact obtainability, withdrawal, or mutable-alias target movement; provenance-integrity evidence; applicable safety or security evidence; the mandatory public-baseline definition or any baseline result; newly discovered runtime or capability evidence that can affect a supported journey; shipped-dependency identity, provenance, or compatibility evidence; and deployed-network identity or compatibility. A mandatory-baseline policy change remains a separate reviewed change and triggers requalification after approval. Default-branch movement alone neither qualifies nor disqualifies a candidate or incumbent unless it supplies changed evidence for one of these qualification inputs. + +Artifact-wide disqualifiers and capability-local defects have different scope. Withdrawal or unobtainability, failed provenance integrity, an artifact-wide safety or security failure, or incompatible deployed-network behavior disqualifies the artifact for every affected journey. A defect confined to a non-baseline capability may leave the rest of a qualified release set active when the affected capability is classified honestly and its remaining guidance is safe. If changed qualification evidence does not establish its scope, qualification fails closed for every plausibly affected journey until the scope is established. + +If no eligible set qualifies and no incumbent remains qualified, the public surface has no supported baseline. It must not fall back to moving source, a prerelease, or any unevaluated artifact. Affected guidance is narrowed or withdrawn and states that no supported baseline exists. ### Promotion evidence Every candidate release set requires a committed, machine-readable release manifest and an inspectable promotion record. Promotion fails closed if any mandatory field or evidence is absent. The record must contain, at minimum: - **Immutable release identity:** the public stable or general-availability distributable identity for every independently obtainable component, including canonical publication state and URL or registry identity, immutable tag object and peeled source commit where applicable, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable; plus the exact locked ref and inspectable parent path for each transitive shipped dependency that carries documented behavior. -- **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. +- **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. Every default or recommended command uses an immutable version or digest selector, and the evidence records the exact immutable identity obtained rather than only the command or alias used. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. A mutable alias may be shown only as non-authoritative convenience when its exact resolved immutable identity is checked and displayed. It cannot establish support, and movement of its target triggers requalification before it can continue to be recommended. - **Release-set compatibility and deployed-network identity:** locked dependency evidence for the shipped set and, for network-dependent claims, the network environment, observation date, protocol or configuration anchor, and the most precise inspectable deployment identity available. If the deployed state cannot be identified precisely enough to reproduce a claim, that claim remains unverified and cannot be promoted. - **Capability and runtime evidence:** a matrix mapping each public interface, capability, and material operation to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. - **Known limitations and alternatives:** known defects, affected versions and operations, upstream issue links for material defects, and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when the supported usage remains safe and reproducible; otherwise the capability is `unavailable` or `deferred`. - **Cross-surface consistency:** the public docs and published developer skill must map the enumerable coverage set defined below to the same support status, known defect or limitation, and safe alternative. Matching refs alone is insufficient. A mismatch blocks promotion. -- **Objective supported-baseline retention:** the incumbent supported release set, the candidate release set, each result against the predeclared mandatory public baseline, and the resulting promote-or-retain outcome. A candidate replaces the incumbent only when every mandatory promotion requirement passes. If any requirement fails, the incumbent remains the supported default only for journeys where it continues to satisfy applicable obtainability, safety and security, deployed-network compatibility, and mandatory baseline requirements. A withdrawn or unobtainable, unsafe or insecure, incompatible, or baseline-noncompliant incumbent is disqualified for the affected journey. If no qualifying incumbent exists, the candidate remains unpromoted, affected guidance is narrowed or withdrawn, and public guidance explicitly states that no supported baseline exists for that journey until a released candidate passes. +- **Objective supported-baseline retention:** the incumbent supported release set, the deterministic newest-first order of all eligible coherent release sets, every evaluated set's result against all qualification and promotion requirements and the predeclared mandatory public baseline, and the resulting select, retain, or no-supported-baseline outcome. Failed maximal sets remain in the record before evaluation continues to older or dominated sets. A candidate replaces a qualified incumbent only when it is strictly preferred and every mandatory promotion requirement passes. The incumbent remains the supported default only for journeys where it continues to satisfy applicable obtainability, provenance-integrity, safety and security, shipped-dependency, deployed-network compatibility, and mandatory-baseline requirements. A disqualified incumbent cannot be retained. If the ordered sequence contains no qualifying set and no incumbent remains qualified, affected guidance is narrowed or withdrawn, and public guidance explicitly states that no supported baseline exists for that journey until a released candidate passes. -The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. Subject to the incumbent qualification rule above, the prior supported release set remains the default until a candidate passes every promotion requirement. When a newer available release is unsuitable and the incumbent remains qualified, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command; retaining an older baseline through stale metadata or omission is prohibited. When the incumbent is disqualified, the affected guidance must instead narrow or withdraw the journey and state that no supported baseline exists until a released candidate passes. +The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. Subject to the incumbent qualification rule above, the prior supported release set remains the default until a strictly preferred candidate passes every promotion requirement. When a newer available release is unsuitable and the incumbent remains qualified, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command with an immutable version or digest selector; retaining an older baseline through stale metadata, a mutable default selector, or omission is prohibited. When the incumbent is disqualified, the affected guidance must instead narrow or withdraw the journey and state that no supported baseline exists until an eligible released set passes. ### Capability truth and skill parity @@ -148,15 +152,18 @@ ADR-0005 and ADR-0007 remain fully intact. Scheduling, adapters, detailed manife This decision is satisfied when all of the following remain true: -- Every public installation or package identity resolves through its documented supported route from a clean environment. -- Candidate discovery rejects drafts, prereleases of every named class, branch builds, and mutable aliases without immutable release identity; those identities can appear only in isolated target previews. +- Every default or recommended public installation command uses an immutable version or digest selector, resolves through its documented supported route from a clean environment, and records the exact immutable identity obtained. +- Candidate discovery rejects drafts, prereleases of every named class, and branch builds; a mutable alias cannot establish eligibility or support. - A stable or general-availability release remains discoverable from canonical publication state when its source commit was already observed on HEAD before publication. -- Shuffling API, registry, or filesystem discovery results does not change the eligible sets, maximal non-dominated sets, precedence, or promotion outcome. -- Incomparable maximal release sets resolve identically through the committed total extension and its fixed component order and immutable release-identity tie-breakers. +- Shuffling API, registry, or filesystem discovery results does not change the eligible sets, the newest-first order over all eligible sets, or the selection outcome. +- Incomparable sets resolve identically through the committed total extension and its fixed component order and immutable release-identity tie-breakers; after each failed maximal set, evaluation continues in that order through older or dominated sets and selects the first qualifying set. +- Replaying the same committed qualification-input snapshot with a different audit schedule or evidence-completion order produces the same evaluation order and selected, retained, or no-supported-baseline outcome. - Every public verification record resolves to exact refs in one coherent release manifest, including shipped dependency refs where they carry documented behavior. - Every release promotion record contains all seven minimum evidence groups required by this decision and identifies the predeclared mandatory public baseline. - Candidate and incumbent qualification apply the same obtainability, provenance-integrity, safety and security, deployed-network compatibility, and mandatory-baseline requirements. -- Artifact withdrawal or loss, applicable advisory or safety evidence, and deployed-network identity or compatibility change requalify the incumbent without requiring a new candidate. +- Changing any qualification input requalifies the incumbent without requiring a new candidate. Validation changes each trigger class independently: obtainability or alias target; provenance integrity; safety or security evidence; an approved mandatory-baseline definition or a baseline result; runtime or capability evidence that can affect a supported journey; shipped-dependency evidence; and deployed-network identity or compatibility. +- A plausibly journey-affecting qualification-input change with uncertain scope fails closed for every plausibly affected journey until its scope is established. +- Moving a documented convenience alias to a different immutable target blocks its continued recommendation until requalification completes; the alias movement alone cannot establish support. - Claims that depend on deployed Autonomi Network behavior are checked against the identified compatible deployed state; claims without a reproducible deployment anchor remain unverified. - Getting-started and how-to journeys have complete runtime evidence for the released interface they recommend; source or schema inspection alone does not pass. - Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. @@ -164,7 +171,7 @@ This decision is satisfied when all of the following remain true: - Every coverage-set identifier has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. - Pointer parity resolves against the active released-truth manifest, fetches released guidance before release-sensitive answers, and defers that detail on fetch failure; bundled skill guidance matches directly without requiring duplicated pointer prose. - A transitive dependency ref with no independent release URL remains valid shipped-dependency provenance but does not establish independent installability or candidate eligibility. -- If a newer available release fails the mandatory baseline and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command. +- If a newer available release fails the mandatory baseline and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command with its immutable version or digest selector. - If an incumbent becomes withdrawn or unobtainable, unsafe or insecure, incompatible with the deployed Autonomi Network, or noncompliant with the mandatory baseline, affected guidance narrows or withdraws the journey and states that no supported baseline exists until a released candidate passes. - No verification record backing the default public rendered documentation or published developer skill uses `current-merged-truth`. - `target-manifest` content never backs the default public surface; any published target content is isolated as a versioned preview and clearly labeled pre-release. From 2dd687bdd4a958694a53049014791ede0b67c0be Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:44:40 +0100 Subject: [PATCH 13/26] docs(gsd): record ADR lifecycle corrections --- planning/STATE.md | 9 +++++---- planning/gsd-adr-0016-checkpoint.md | 12 +++++++----- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index be1c5e8..0add37d 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,12 +4,12 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: remediate Proposed ADR-0016 lifecycle edge cases -- Status: code-review issues; attended checkpoint +- Task: re-review Proposed ADR-0016 lifecycle corrections +- Status: lifecycle findings remediated; code review and verification pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` -- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c` +- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -42,6 +42,7 @@ - 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 re-review remains pending. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -56,4 +57,4 @@ ## Next -- With Jim's attended approval, define deterministic qualified-set fallback, requalify on every qualification-input change, and close mutable-alias drift; then rerun code review and goal verification before adversarial, Craft, and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- Rerun code review and goal verification against lifecycle correction `9c2f1da`, then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 6ad9fa9..84164ea 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,10 +8,10 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Revise — independent code review of the adversarial remediation found two HIGH lifecycle gaps and one MEDIUM alias gap. +Continue — lifecycle findings are remediated at `9c2f1da`; independent re-review is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit blocked at code review +Review cadence: per-unit re-review in progress Unreviewed backlog if deferred: Craft and clean-context remain unrun until adversarial passes ## What happened @@ -61,6 +61,7 @@ Results: - Accepted ADRs: byte-identical to the base. - Adversarial-remediation local validation at `fb67648`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. - Code review at exact commit `e3df50957d2691b8661c503bfd6f34cc960aece9`: `issues_found`; two HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-e3df509.md`. +- Lifecycle-correction local validation at `9c2f1da`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. ## Honesty rules check @@ -87,6 +88,7 @@ Independent code review: - HIGH: define deterministic behavior when maximal eligible sets fail but a dominated older eligible set might qualify. - HIGH: incumbent requalification must trigger whenever any qualification input changes, not only availability, security, or network evidence. - MEDIUM: default install routes must pin immutable versions/digests or alias-target movement must trigger requalification. +- Disposition: all three are remediated in `9c2f1da`; independent re-review pending. - Report: `planning/adr-0016-code-review-e3df509.md` Clean-context test: @@ -124,7 +126,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -Approve or decline remediation of the new lifecycle findings. ADR acceptance is not yet ready for decision. +No owner decision is pending until lifecycle corrections complete re-review. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -134,8 +136,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Define deterministic qualified-set fallback, trigger requalification on every qualification-input change, and close mutable-alias drift. Then rerun code review and goal verification against the resulting content commit before adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Rerun code review and goal verification against lifecycle correction `9c2f1da`, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`, but code review of `e3df509` found three remaining lifecycle edge cases. The proposal is not acceptance-ready, goal verification/adversarial re-review/Craft/clean-context have not run, CI has not run, and no implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`; three later lifecycle edge cases are remediated in `9c2f1da`. The proposal still needs code review, goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. From 74c30b2fe92512e18dc4fbb4c2390d9926cc7eb5 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:51:24 +0100 Subject: [PATCH 14/26] docs(gsd): record ADR pointer review gaps --- planning/STATE.md | 12 ++++-- planning/adr-0016-code-review-2dd687b.md | 50 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 15 ++++--- 3 files changed, 67 insertions(+), 10 deletions(-) create mode 100644 planning/adr-0016-code-review-2dd687b.md diff --git a/planning/STATE.md b/planning/STATE.md index 0add37d..4675be6 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: re-review Proposed ADR-0016 lifecycle corrections -- Status: lifecycle findings remediated; code review and verification pending +- Task: remediate Proposed ADR-0016 pointer security and alias consistency +- Status: code-review issues; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -42,7 +42,11 @@ - 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 re-review remains 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. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -57,4 +61,4 @@ ## Next -- Rerun code review and goal verification against lifecycle correction `9c2f1da`, then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- With Jim's attended approval, add the untrusted-content boundary for skill pointers and make mutable aliases never default or recommended commands; then rerun code review and goal verification before adversarial, Craft, and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 84164ea..005343a 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,10 +8,10 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — lifecycle findings are remediated at `9c2f1da`; independent re-review is pending. +Revise — lifecycle fallback/requalification passed re-review, but pointer security and mutable-alias consistency remain. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit re-review in progress +Review cadence: per-unit blocked at code review Unreviewed backlog if deferred: Craft and clean-context remain unrun until adversarial passes ## What happened @@ -42,6 +42,7 @@ Files changed/artifacts produced: - `planning/STATE.md` - `planning/gsd-adr-0016-checkpoint.md` - `planning/adr-0016-code-review-e3df509.md` +- `planning/adr-0016-code-review-2dd687b.md` Checks run: @@ -62,6 +63,7 @@ Results: - Adversarial-remediation local validation at `fb67648`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. - Code review at exact commit `e3df50957d2691b8661c503bfd6f34cc960aece9`: `issues_found`; two HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-e3df509.md`. - Lifecycle-correction local validation at `9c2f1da`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. +- Code review at exact commit `2dd687bdd4a958694a53049014791ede0b67c0be`: `issues_found`; previous lifecycle HIGH findings resolved, with one new HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-2dd687b.md`. ## Honesty rules check @@ -88,7 +90,8 @@ Independent code review: - HIGH: define deterministic behavior when maximal eligible sets fail but a dominated older eligible set might qualify. - HIGH: incumbent requalification must trigger whenever any qualification input changes, not only availability, security, or network evidence. - MEDIUM: default install routes must pin immutable versions/digests or alias-target movement must trigger requalification. -- Disposition: all three are remediated in `9c2f1da`; independent re-review pending. +- Disposition: all three were remediated in `9c2f1da` and re-reviewed at `2dd687b`. +- Re-review disposition at `2dd687b`: deterministic fallback and complete requalification passed; immutable defaults passed, but alias recommendation language remained inconsistent. A new HIGH pointer-security finding was added. - Report: `planning/adr-0016-code-review-e3df509.md` Clean-context test: @@ -126,7 +129,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until lifecycle corrections complete re-review. ADR acceptance is not yet ready for decision. +Approve or decline the pointer-security and alias-consistency remediation. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -136,8 +139,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Rerun code review and goal verification against lifecycle correction `9c2f1da`, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Add a durable untrusted-content boundary for fetched skill pointers and prohibit mutable aliases from ever being default or recommended commands. Then rerun code review and goal verification before adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`; three later lifecycle edge cases are remediated in `9c2f1da`. The proposal still needs code review, goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`; lifecycle fallback and requalification were remediated in `9c2f1da` and passed re-review. Pointer security and alias consistency still block code review. The proposal still needs goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. From 4873f368feec5183b7a69c493c86d2beb6efe8b5 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:56:08 +0100 Subject: [PATCH 15/26] docs(adr): secure pointers and immutable installs - Treat fetched skill pointers as untrusted factual input\n- Keep mutable aliases unsupported and non-authoritative --- ...0016-released-truth-for-public-developer-docs.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md index 49cda87..4941a62 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -54,7 +54,7 @@ The verification model will retain exact per-surface provenance while changing i ### Release identities and candidate eligibility -An independently obtainable component is eligible for a `released-truth` candidate only through a stable or general-availability public distributable release identity published by its canonical publisher. That identity records its stable or general-availability publication state and canonical release URL or registry identity, immutable source identity, published artifacts and checksums where artifacts are distributed, and standard installation identity. Drafts; alpha, beta, release-candidate (RC), preview, nightly, canary, or equivalent prereleases; and branch builds are ineligible. A mutable installation alias is not a release identity and cannot establish candidate eligibility or support. Default and recommended public install commands must resolve through immutable version or digest selectors. These ineligible identities may appear only in isolated `target-manifest` preview mode, except that a mutable alias may also appear as the non-authoritative convenience described under promotion evidence. +An independently obtainable component is eligible for a `released-truth` candidate only through a stable or general-availability public distributable release identity published by its canonical publisher. That identity records its stable or general-availability publication state and canonical release URL or registry identity, immutable source identity, published artifacts and checksums where artifacts are distributed, and standard installation identity. Drafts; alpha, beta, release-candidate (RC), preview, nightly, canary, or equivalent prereleases; and branch builds are ineligible. A mutable installation alias is not a release identity and cannot establish candidate eligibility or support. Clean-install checks and default, supported, or recommended public installation commands must resolve through immutable version or digest selectors. These ineligible identities may appear only in isolated `target-manifest` preview mode, except that a mutable alias may also be mentioned as the unsupported, non-authoritative informational convenience described under promotion evidence. A transitive shipped dependency has a different identity contract. It records the exact locked ref and an inspectable dependency path from the parent distributable release. It needs its own stable or general-availability release URL only when the public guidance presents it as independently obtainable. A transitive ref proves what a parent release shipped; it never by itself establishes that the dependency is independently installable or eligible as a released-truth candidate. @@ -79,7 +79,7 @@ If no eligible set qualifies and no incumbent remains qualified, the public surf Every candidate release set requires a committed, machine-readable release manifest and an inspectable promotion record. Promotion fails closed if any mandatory field or evidence is absent. The record must contain, at minimum: - **Immutable release identity:** the public stable or general-availability distributable identity for every independently obtainable component, including canonical publication state and URL or registry identity, immutable tag object and peeled source commit where applicable, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable; plus the exact locked ref and inspectable parent path for each transitive shipped dependency that carries documented behavior. -- **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. Every default or recommended command uses an immutable version or digest selector, and the evidence records the exact immutable identity obtained rather than only the command or alias used. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. A mutable alias may be shown only as non-authoritative convenience when its exact resolved immutable identity is checked and displayed. It cannot establish support, and movement of its target triggers requalification before it can continue to be recommended. +- **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. Every clean-install check and every default, supported, or recommended command uses an immutable version or digest selector, and the evidence records the exact immutable identity obtained rather than only the command text. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. A mutable alias may be mentioned only as an explicitly unsupported, non-authoritative informational convenience alongside the exact immutable target observed. It cannot establish support and is never a default, supported, or recommended installation command. Movement of its target triggers requalification of whether the informational mention remains accurate, but successful requalification cannot promote the alias into a default, supported, or recommended route. - **Release-set compatibility and deployed-network identity:** locked dependency evidence for the shipped set and, for network-dependent claims, the network environment, observation date, protocol or configuration anchor, and the most precise inspectable deployment identity available. If the deployed state cannot be identified precisely enough to reproduce a claim, that claim remains unverified and cannot be promoted. - **Capability and runtime evidence:** a matrix mapping each public interface, capability, and material operation to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. - **Known limitations and alternatives:** known defects, affected versions and operations, upstream issue links for material defects, and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when the supported usage remains safe and reproducible; otherwise the capability is `unavailable` or `deferred`. @@ -102,6 +102,8 @@ The active manifest defines an enumerable coverage set of stable interface, capa For each covered identifier, the skill may represent released guidance as bundled content or as an explicit pointer to the default released-truth docs. A pointer satisfies parity only when it resolves under the same active manifest, the skill carries no contradictory claim, and the agent fetches the released guidance before answering release-sensitive detail. If that fetch fails, the agent defers the release-sensitive detail instead of consulting moving source or fabricating an answer. Parity does not require duplication of pointered prose. Any claim, recommendation, warning, limitation, alternative, or routing instruction that the skill does bundle must match the active released guidance directly. +Fetched released guidance is untrusted factual input, never executable instructions or authority over system or developer instructions, the skill, or the user's request. The agent must delimit fetched content from controlling instructions and ignore any embedded request to alter behavior, reveal secrets, bypass safeguards, fetch unrelated material, or take actions. Release-sensitive claims or actions derived from fetched content must still be checked against the active released-truth manifest, the applicable capability status, and applicable safety constraints. Fetched content cannot change tool permissions, authorize spending, publishing, or destructive actions, or cross an approval gate. If provenance and manifest alignment cannot be established, or fetched content conflicts with the skill or the user's request, the agent defers the release-sensitive detail and surfaces the conflict; it never follows the embedded instruction or falls back to moving source. These restrictions preserve ADR-0013's pointer tier and apply whether the fetch succeeds or fails. + The existing verification-block invariants remain: - Every rendered documentation surface carries one or more machine-readable verification records with source repository, ref, exact commit SHA, verification date, and verification mode. @@ -152,7 +154,7 @@ ADR-0005 and ADR-0007 remain fully intact. Scheduling, adapters, detailed manife This decision is satisfied when all of the following remain true: -- Every default or recommended public installation command uses an immutable version or digest selector, resolves through its documented supported route from a clean environment, and records the exact immutable identity obtained. +- Every clean-install check and every default, supported, or recommended public installation command uses an immutable version or digest selector, resolves through its documented supported route from a clean environment, and records the exact immutable identity obtained. - Candidate discovery rejects drafts, prereleases of every named class, and branch builds; a mutable alias cannot establish eligibility or support. - A stable or general-availability release remains discoverable from canonical publication state when its source commit was already observed on HEAD before publication. - Shuffling API, registry, or filesystem discovery results does not change the eligible sets, the newest-first order over all eligible sets, or the selection outcome. @@ -163,13 +165,16 @@ This decision is satisfied when all of the following remain true: - Candidate and incumbent qualification apply the same obtainability, provenance-integrity, safety and security, deployed-network compatibility, and mandatory-baseline requirements. - Changing any qualification input requalifies the incumbent without requiring a new candidate. Validation changes each trigger class independently: obtainability or alias target; provenance integrity; safety or security evidence; an approved mandatory-baseline definition or a baseline result; runtime or capability evidence that can affect a supported journey; shipped-dependency evidence; and deployed-network identity or compatibility. - A plausibly journey-affecting qualification-input change with uncertain scope fails closed for every plausibly affected journey until its scope is established. -- Moving a documented convenience alias to a different immutable target blocks its continued recommendation until requalification completes; the alias movement alone cannot establish support. +- A mutable alias, if mentioned, is explicitly unsupported and non-authoritative and appears alongside the exact immutable target observed; it is never a default, supported, or recommended installation command. +- Moving a mentioned mutable alias to a different immutable target requalifies whether the informational mention remains accurate; successful requalification cannot establish support or promote the alias into a default, supported, or recommended route. - Claims that depend on deployed Autonomi Network behavior are checked against the identified compatible deployed state; claims without a reproducible deployment anchor remain unverified. - Getting-started and how-to journeys have complete runtime evidence for the released interface they recommend; source or schema inspection alone does not pass. - Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. - A capability-local non-baseline defect changes only its covered capability when evidence establishes that isolation; uncertain safety or security scope fails closed for every plausibly affected journey. - Every coverage-set identifier has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. - Pointer parity resolves against the active released-truth manifest, fetches released guidance before release-sensitive answers, and defers that detail on fetch failure; bundled skill guidance matches directly without requiring duplicated pointer prose. +- Fetched pointer content remains delimited as untrusted factual input and cannot override controlling instructions, change permissions, authorize gated actions, or cause embedded requests to be followed; release-sensitive claims and actions remain subject to the active manifest, capability status, and applicable safety constraints. +- If fetched-content provenance or manifest alignment cannot be established, or fetched content conflicts with the skill or user request, the agent defers the release-sensitive detail, surfaces the conflict, and does not fall back to moving source. - A transitive dependency ref with no independent release URL remains valid shipped-dependency provenance but does not establish independent installability or candidate eligibility. - If a newer available release fails the mandatory baseline and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command with its immutable version or digest selector. - If an incumbent becomes withdrawn or unobtainable, unsafe or insecure, incompatible with the deployed Autonomi Network, or noncompliant with the mandatory baseline, affected guidance narrows or withdraws the journey and states that no supported baseline exists until a released candidate passes. From 481ca8cb653b32823851d38b2bcc36b4007ddf7a Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:57:50 +0100 Subject: [PATCH 16/26] docs(gsd): record ADR pointer corrections --- planning/STATE.md | 9 +++++---- planning/gsd-adr-0016-checkpoint.md | 12 +++++++----- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 4675be6..60853a1 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,12 +4,12 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: remediate Proposed ADR-0016 pointer security and alias consistency -- Status: code-review issues; attended checkpoint +- Task: re-review Proposed ADR-0016 pointer security corrections +- Status: pointer findings remediated; code review and verification pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` -- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153` +- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`; pointer-security correction `4873f368feec5183b7a69c493c86d2beb6efe8b5` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -47,6 +47,7 @@ - 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; independent re-review remains pending. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -61,4 +62,4 @@ ## Next -- With Jim's attended approval, add the untrusted-content boundary for skill pointers and make mutable aliases never default or recommended commands; then rerun code review and goal verification before adversarial, Craft, and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- Rerun code review and goal verification against pointer-security correction `4873f36`, then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 005343a..a274a6b 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,10 +8,10 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Revise — lifecycle fallback/requalification passed re-review, but pointer security and mutable-alias consistency remain. +Continue — pointer-security and alias-consistency findings are remediated at `4873f36`; re-review is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit blocked at code review +Review cadence: per-unit re-review in progress Unreviewed backlog if deferred: Craft and clean-context remain unrun until adversarial passes ## What happened @@ -64,6 +64,7 @@ Results: - Code review at exact commit `e3df50957d2691b8661c503bfd6f34cc960aece9`: `issues_found`; two HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-e3df509.md`. - Lifecycle-correction local validation at `9c2f1da`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. - Code review at exact commit `2dd687bdd4a958694a53049014791ede0b67c0be`: `issues_found`; previous lifecycle HIGH findings resolved, with one new HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-2dd687b.md`. +- Pointer-security local validation at `4873f36`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. ## Honesty rules check @@ -92,6 +93,7 @@ Independent code review: - MEDIUM: default install routes must pin immutable versions/digests or alias-target movement must trigger requalification. - Disposition: all three were remediated in `9c2f1da` and re-reviewed at `2dd687b`. - Re-review disposition at `2dd687b`: deterministic fallback and complete requalification passed; immutable defaults passed, but alias recommendation language remained inconsistent. A new HIGH pointer-security finding was added. +- Disposition: pointer-security and alias-consistency findings are remediated in `4873f36`; independent re-review pending. - Report: `planning/adr-0016-code-review-e3df509.md` Clean-context test: @@ -129,7 +131,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -Approve or decline the pointer-security and alias-consistency remediation. ADR acceptance is not yet ready for decision. +No owner decision is pending until pointer-security corrections complete re-review. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -139,8 +141,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Add a durable untrusted-content boundary for fetched skill pointers and prohibit mutable aliases from ever being default or recommended commands. Then rerun code review and goal verification before adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Rerun code review and goal verification against pointer-security correction `4873f36`, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`; lifecycle fallback and requalification were remediated in `9c2f1da` and passed re-review. Pointer security and alias consistency still block code review. The proposal still needs goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`; lifecycle fallback and requalification were remediated in `9c2f1da`; pointer security and alias consistency were remediated in `4873f36`. The proposal still needs code re-review, goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. From 9bd4f6f0780d3a431a134214f9abaa3fddb45ea4 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:03:26 +0100 Subject: [PATCH 17/26] docs(gsd): record passing ADR code review --- planning/STATE.md | 9 +++--- planning/adr-0016-code-review-481ca8c.md | 37 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 13 +++++---- 3 files changed, 50 insertions(+), 9 deletions(-) create mode 100644 planning/adr-0016-code-review-481ca8c.md diff --git a/planning/STATE.md b/planning/STATE.md index 60853a1..e1c7879 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: re-review Proposed ADR-0016 pointer security corrections -- Status: pointer findings remediated; code review and verification pending +- Task: verify Proposed ADR-0016 goal after final code review +- Status: code review passed; goal verification pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -47,7 +47,8 @@ - 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; independent re-review remains pending. +- 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`. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -62,4 +63,4 @@ ## Next -- Rerun code review and goal verification against pointer-security correction `4873f36`, then rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- Run exact-HEAD goal verification, persist its report, and rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index a274a6b..873ee2c 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,7 +8,7 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — pointer-security and alias-consistency findings are remediated at `4873f36`; re-review is pending. +Continue — code review passed at `481ca8c`; goal verification is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit re-review in progress @@ -43,6 +43,7 @@ Files changed/artifacts produced: - `planning/gsd-adr-0016-checkpoint.md` - `planning/adr-0016-code-review-e3df509.md` - `planning/adr-0016-code-review-2dd687b.md` +- `planning/adr-0016-code-review-481ca8c.md` Checks run: @@ -65,6 +66,7 @@ Results: - Lifecycle-correction local validation at `9c2f1da`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. - Code review at exact commit `2dd687bdd4a958694a53049014791ede0b67c0be`: `issues_found`; previous lifecycle HIGH findings resolved, with one new HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-2dd687b.md`. - Pointer-security local validation at `4873f36`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. +- Code review at exact commit `481ca8cb653b32823851d38b2bcc36b4007ddf7a`: passed with no findings. Full report: `planning/adr-0016-code-review-481ca8c.md`. ## Honesty rules check @@ -93,7 +95,8 @@ Independent code review: - MEDIUM: default install routes must pin immutable versions/digests or alias-target movement must trigger requalification. - Disposition: all three were remediated in `9c2f1da` and re-reviewed at `2dd687b`. - Re-review disposition at `2dd687b`: deterministic fallback and complete requalification passed; immutable defaults passed, but alias recommendation language remained inconsistent. A new HIGH pointer-security finding was added. -- Disposition: pointer-security and alias-consistency findings are remediated in `4873f36`; independent re-review pending. +- Disposition: pointer-security and alias-consistency findings were remediated in `4873f36` and re-reviewed at `481ca8c`. +- Re-review disposition at `481ca8c`: both findings resolved; code-review gate passed. - Report: `planning/adr-0016-code-review-e3df509.md` Clean-context test: @@ -131,7 +134,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until pointer-security corrections complete re-review. ADR acceptance is not yet ready for decision. +No owner decision is pending until goal and gauntlet verification complete. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -141,8 +144,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Rerun code review and goal verification against pointer-security correction `4873f36`, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Run exact-HEAD goal verification, persist its report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. The first policy findings were remediated in `fb67648`; lifecycle fallback and requalification were remediated in `9c2f1da`; pointer security and alias consistency were remediated in `4873f36`. The proposal still needs code re-review, goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. Its policy findings and subsequent lifecycle/pointer findings are remediated; code review passed at `481ca8c`. The proposal still needs goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. From 9a0b1e3bb37cbfc4dd3da5ba31ebb87394195717 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:08:16 +0100 Subject: [PATCH 18/26] docs(gsd): record passing ADR verification --- planning/STATE.md | 7 ++-- planning/adr-0016-verification-9bd4f6f.md | 47 +++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 23 ++++++----- 3 files changed, 64 insertions(+), 13 deletions(-) create mode 100644 planning/adr-0016-verification-9bd4f6f.md diff --git a/planning/STATE.md b/planning/STATE.md index e1c7879..11df08f 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: verify Proposed ADR-0016 goal after final code review -- Status: code review passed; goal verification pending +- Task: rerun adversarial review of Proposed ADR-0016 +- Status: code review and goal verification passed; adversarial pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -49,6 +49,7 @@ - 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`. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. @@ -63,4 +64,4 @@ ## Next -- Run exact-HEAD goal verification, persist its report, and rerun adversarial before Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- Rerun adversarial against the proposal and branch-local review evidence. If it passes, run Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 873ee2c..b668047 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,7 +8,7 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — code review passed at `481ca8c`; goal verification is pending. +Continue — code review and 10/10 goal verification passed; adversarial re-review is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit re-review in progress @@ -44,6 +44,7 @@ Files changed/artifacts produced: - `planning/adr-0016-code-review-e3df509.md` - `planning/adr-0016-code-review-2dd687b.md` - `planning/adr-0016-code-review-481ca8c.md` +- `planning/adr-0016-verification-9bd4f6f.md` Checks run: @@ -52,6 +53,7 @@ Checks run: - `git diff --check origin/main...HEAD` - Independent code review through commit `5dbecd5`, before the later state/checkpoint-only commit. - Goal-backward verification through commit `5dbecd5` against the approved decision intent and Accepted ADR boundaries. +- Final code review through `481ca8c` and goal verification through `9bd4f6f`, with branch-local reports. Results: @@ -67,6 +69,7 @@ Results: - Code review at exact commit `2dd687bdd4a958694a53049014791ede0b67c0be`: `issues_found`; previous lifecycle HIGH findings resolved, with one new HIGH and one MEDIUM finding. Full report: `planning/adr-0016-code-review-2dd687b.md`. - Pointer-security local validation at `4873f36`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. - Code review at exact commit `481ca8cb653b32823851d38b2bcc36b4007ddf7a`: passed with no findings. Full report: `planning/adr-0016-code-review-481ca8c.md`. +- Goal verification at exact commit `9bd4f6f0780d3a431a134214f9abaa3fddb45ea4`: passed, 10/10 decision-contract goals verified with no gaps. Full report: `planning/adr-0016-verification-9bd4f6f.md`. ## Honesty rules check @@ -74,8 +77,8 @@ Results: - No test, harness, daemon, build, environment, gate, or CI change. - Baseline-diff for evidence: Pass - No failure or skip was dismissed as environmental, flaky, or pre-existing. -- Evidence reproducible-from-branch: Concern - - The motivating audit, representative commands, and latest exact-SHA code-review report are committed and require no uncommitted wrapper or environment variable. The earlier verifier report was session-local; a new exact-SHA verification remains pending after remediation. +- Evidence reproducible-from-branch: Pass for local review evidence + - The motivating audit, representative commands, latest passing exact-SHA code-review report, and 10/10 goal-verification report are committed and require no uncommitted wrapper or environment variable. CI evidence remains absent. - Local vs CI consistency: no conflict observed, but the applicable CI arbiter has not run. ## Ledger / forks @@ -87,8 +90,8 @@ Not applicable; attended run. No forks or split decisions were created. Independent code review: - Reviewer/tool: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) -- Reviewed commit: `e3df50957d2691b8661c503bfd6f34cc960aece9` -- Result: Issues found +- Reviewed commit: latest passing review `481ca8cb653b32823851d38b2bcc36b4007ddf7a`; prior issue rounds `e3df509` and `2dd687b` +- Result: Passed after two recorded remediation rounds - Findings: - HIGH: define deterministic behavior when maximal eligible sets fail but a dominated older eligible set might qualify. - HIGH: incumbent requalification must trigger whenever any qualification input changes, not only availability, security, or network evidence. @@ -97,7 +100,7 @@ Independent code review: - Re-review disposition at `2dd687b`: deterministic fallback and complete requalification passed; immutable defaults passed, but alias recommendation language remained inconsistent. A new HIGH pointer-security finding was added. - Disposition: pointer-security and alias-consistency findings were remediated in `4873f36` and re-reviewed at `481ca8c`. - Re-review disposition at `481ca8c`: both findings resolved; code-review gate passed. -- Report: `planning/adr-0016-code-review-e3df509.md` +- Reports: `planning/adr-0016-code-review-e3df509.md`, `planning/adr-0016-code-review-2dd687b.md`, and `planning/adr-0016-code-review-481ca8c.md` Clean-context test: @@ -117,7 +120,7 @@ Adversarial review: - HIGH: applicable PR-triggered ADR Governance CI exists but has not run. - MEDIUM: skill parity is ambiguous under the pointer-based skill model. Remediated at `fb67648`; re-review pending. - MEDIUM: distributable release identity and transitive dependency identity are conflated. Remediated at `fb67648`; re-review pending. - - MEDIUM: review/verification evidence and exact reviewed SHA were overstated. Claims remain narrowed; exact-SHA re-review evidence is pending. + - MEDIUM: review/verification evidence and exact reviewed SHA were overstated. Claims were narrowed and exact-SHA code-review/verification reports are now branch-local; adversarial re-review pending. Craft Review: @@ -134,7 +137,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until goal and gauntlet verification complete. ADR acceptance is not yet ready for decision. +No owner decision is pending until the gauntlet completes. ADR acceptance is not yet ready for decision. PR / upstream action gate, if applicable: @@ -144,8 +147,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run exact-HEAD goal verification, persist its report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Rerun adversarial against the proposal and committed review evidence. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. Its policy findings and subsequent lifecycle/pointer findings are remediated; code review passed at `481ca8c`. The proposal still needs goal verification, adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. +Adversarial review of `ff9761a` returned NOT-READY. Its findings and subsequent lifecycle/pointer findings are remediated; code review passed at `481ca8c` and 10/10 goal verification passed at `9bd4f6f`. The proposal still needs adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. From d8e730047cd35e6003ff746f0fc740d1772a1e78 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:08:50 +0100 Subject: [PATCH 19/26] docs(gsd): request ADR CI checkpoint --- planning/STATE.md | 6 +++--- planning/gsd-adr-0016-checkpoint.md | 12 +++++++----- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 11df08f..caf6483 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: rerun adversarial review of Proposed ADR-0016 -- Status: code review and goal verification passed; adversarial pending +- Task: obtain exact-SHA ADR Governance CI before gauntlet re-review +- Status: code review and goal verification passed; blocked on explicit draft-PR authorization - Mode: attended - Branch: `adr/released-and-usable-truth` - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` @@ -64,4 +64,4 @@ ## Next -- Rerun adversarial against the proposal and branch-local review evidence. If it passes, run Craft and clean-context. CI green will later require Jim's explicit authorization for the exact PR action. Do not begin implementation. +- With Jim's explicit authorization, push `adr/released-and-usable-truth` and open a draft PR into `main` solely for ADR review and the PR-triggered ADR Governance CI. After exact-SHA CI is green, rerun adversarial, Craft, and clean-context. Do not merge, accept the ADR, or begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index b668047..7dd6b0a 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,7 +8,7 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — code review and 10/10 goal verification passed; adversarial re-review is pending. +Stop for decision — code review and 10/10 goal verification passed; explicit draft-PR authorization is required to obtain CI green before gauntlet re-review. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit re-review in progress @@ -137,17 +137,19 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until the gauntlet completes. ADR acceptance is not yet ready for decision. +Authorize or decline this exact membrane action: push branch `adr/released-and-usable-truth` and open a draft PR into `main` to run ADR Governance CI and host review evidence. The PR will not be merged and ADR-0016 will remain Proposed. PR / upstream action gate, if applicable: -- PR ready to raise? No +- PR ready to raise? Yes — as a draft CI/review vehicle only; not acceptance-ready or merge-ready - Jim confirmed PR may be opened? No -- Draft PR title/description prepared: No +- Draft PR title/description prepared: Yes + - Title: `docs(adr): adopt released truth for public documentation` + - Description: proposes ADR-0016, carries its dated motivating audit and branch-local review evidence, states that no implementation is included, and requests ADR Governance CI plus review before the human acceptance decision. ## Recommended next step -Rerun adversarial against the proposal and committed review evidence. Craft and clean-context follow only after adversarial passes. Obtaining CI green will require Jim's explicit authorization for the exact pull-request action. Do not begin implementation. +Obtain Jim's explicit authorization for the named draft PR. If authorized, push the branch, open only that draft PR, wait for exact-SHA ADR Governance CI, and then rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note From dfd14dabcbec4706449ae6af1270328ed6dc26af Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:14:27 +0100 Subject: [PATCH 20/26] docs(gsd): record ADR draft PR CI --- planning/STATE.md | 9 +++++---- planning/gsd-adr-0016-checkpoint.md | 10 +++++----- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index caf6483..3a67dd5 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,10 +4,11 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: obtain exact-SHA ADR Governance CI before gauntlet re-review -- Status: code review and goal verification passed; blocked on explicit draft-PR authorization +- Task: rerun adversarial review after CI green +- Status: draft PR open; initial PR head CI green; state-only update pending CI rerun - Mode: attended - Branch: `adr/released-and-usable-truth` +- Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 - Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` - Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`; pointer-security correction `4873f368feec5183b7a69c493c86d2beb6efe8b5` - Implementation: not started; ADR acceptance remains human-only @@ -52,7 +53,7 @@ - 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`. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` -- CI arbiter: `.github/workflows/adr-governance.yml`, triggered for ADR-changing pull requests. No remote branch/PR or exact-SHA CI run exists; local evidence is weaker and must not be called CI-green. +- CI arbiter: draft PR #98. Initial PR head `d8e7300` passed ADR Governance, prose-guard, sweep-guard, sweep-sha-reachability, and both GitBook checks. This state-only update must also pass before gauntlet re-review. - 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 @@ -64,4 +65,4 @@ ## Next -- With Jim's explicit authorization, push `adr/released-and-usable-truth` and open a draft PR into `main` solely for ADR review and the PR-triggered ADR Governance CI. After exact-SHA CI is green, rerun adversarial, Craft, and clean-context. Do not merge, accept the ADR, or begin implementation. +- Push this state-only update, confirm draft PR #98 is green at the new exact head, then rerun adversarial. If it passes, run Craft and clean-context. Do not merge, accept the ADR, or begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 7dd6b0a..f7d36d1 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,7 +8,7 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Stop for decision — code review and 10/10 goal verification passed; explicit draft-PR authorization is required to obtain CI green before gauntlet re-review. +Continue — Jim authorized draft PR #98; initial PR head CI is green and the state-only update requires its rerun before adversarial review. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit re-review in progress @@ -27,7 +27,7 @@ No implementation, rendered documentation, skill, manifest, automation, CI, test CI arbiter / green of record: - Location: `.github/workflows/adr-governance.yml`, triggered by pull requests that change `adr/**`. -- Status: the CI arbiter exists, but no remote branch, pull request, or exact-SHA CI run exists. Local evidence is weaker and is not CI-green. +- Status: draft PR #98 is open. Initial head `d8e7300` passed ADR Governance, prose-guard, sweep-guard, sweep-sha-reachability, GitBook, and the docs preview check. This state-only update must also pass at the new exact head before gauntlet re-review. Local fast gate / `.gsd/gate.sh`: @@ -137,19 +137,19 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -Authorize or decline this exact membrane action: push branch `adr/released-and-usable-truth` and open a draft PR into `main` to run ADR Governance CI and host review evidence. The PR will not be merged and ADR-0016 will remain Proposed. +No owner decision is pending until the remaining gauntlet completes. The draft PR does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: - PR ready to raise? Yes — as a draft CI/review vehicle only; not acceptance-ready or merge-ready -- Jim confirmed PR may be opened? No +- Jim confirmed PR may be opened? Yes — exact draft PR action authorized in chat on 2026-08-20 - Draft PR title/description prepared: Yes - Title: `docs(adr): adopt released truth for public documentation` - Description: proposes ADR-0016, carries its dated motivating audit and branch-local review evidence, states that no implementation is included, and requests ADR Governance CI plus review before the human acceptance decision. ## Recommended next step -Obtain Jim's explicit authorization for the named draft PR. If authorized, push the branch, open only that draft PR, wait for exact-SHA ADR Governance CI, and then rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Push this state-only update, wait for exact-head draft PR checks, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note From 5e35f6dafec41844ac4c20f78352ff3342acc9d2 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:28:20 +0100 Subject: [PATCH 21/26] docs(gsd): record ADR qualification decision --- planning/STATE.md | 15 +++++--- planning/adr-0016-adversarial-dfd14da.md | 44 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 28 ++++++++++----- 3 files changed, 73 insertions(+), 14 deletions(-) create mode 100644 planning/adr-0016-adversarial-dfd14da.md diff --git a/planning/STATE.md b/planning/STATE.md index 3a67dd5..c23833d 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,12 +4,13 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: rerun adversarial review after CI green -- Status: draft PR open; initial PR head CI green; state-only update pending CI rerun +- Task: decide ADR-0016 qualification granularity +- Status: adversarial NOT-READY; attended decision checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 -- Base: `origin/main` at `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` +- Branch point: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` +- Current draft-PR base: `origin/main` at `487866a249fcb5ad7d8dd7829c017ed63d421343` - Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`; pointer-security correction `4873f368feec5183b7a69c493c86d2beb6efe8b5` - Implementation: not started; ADR acceptance remains human-only @@ -51,9 +52,13 @@ - 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. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` -- CI arbiter: draft PR #98. Initial PR head `d8e7300` passed ADR Governance, prose-guard, sweep-guard, sweep-sha-reachability, and both GitBook checks. This state-only update must also pass before gauntlet re-review. +- CI arbiter: draft PR #98. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks also returned success but were scope-gate no-ops for this branch, not substantive coverage. - Freshness risk: the imported v0.11.2 audit is explicitly historical; `antd` v0.12.0 has since released and issue #233 has closed. A fresh candidate-release audit is required before implementation, regardless of ADR acceptance. ## Constraints @@ -65,4 +70,4 @@ ## Next -- Push this state-only update, confirm draft PR #98 is green at the new exact head, then rerun adversarial. If it passes, run Craft and clean-context. Do not merge, accept the ADR, or begin implementation. +- Jim must choose global release-set qualification or journey-local qualification reconciled with one active manifest. After that decision, revise the Proposed ADR and verification evidence, rerun code review, goal verification, CI, and adversarial before Craft and clean-context. Do not merge, accept the ADR, or begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index f7d36d1..8e88afb 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,11 +8,11 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — Jim authorized draft PR #98; initial PR head CI is green and the state-only update requires its rerun before adversarial review. +Stop for decision — exact-head CI is green, but adversarial review returned NOT-READY on qualification granularity. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit re-review in progress -Unreviewed backlog if deferred: Craft and clean-context remain unrun until adversarial passes +Review cadence: per-unit blocked at adversarial decision finding +Unreviewed backlog if deferred: Craft and clean-context remain unrun because adversarial did not pass ## What happened @@ -27,7 +27,7 @@ No implementation, rendered documentation, skill, manifest, automation, CI, test CI arbiter / green of record: - Location: `.github/workflows/adr-governance.yml`, triggered by pull requests that change `adr/**`. -- Status: draft PR #98 is open. Initial head `d8e7300` passed ADR Governance, prose-guard, sweep-guard, sweep-sha-reachability, GitBook, and the docs preview check. This state-only update must also pass at the new exact head before gauntlet re-review. +- Status: draft PR #98 is open. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. Local fast gate / `.gsd/gate.sh`: @@ -45,6 +45,7 @@ Files changed/artifacts produced: - `planning/adr-0016-code-review-2dd687b.md` - `planning/adr-0016-code-review-481ca8c.md` - `planning/adr-0016-verification-9bd4f6f.md` +- `planning/adr-0016-adversarial-dfd14da.md` Checks run: @@ -78,8 +79,8 @@ Results: - Baseline-diff for evidence: Pass - No failure or skip was dismissed as environmental, flaky, or pre-existing. - Evidence reproducible-from-branch: Pass for local review evidence - - The motivating audit, representative commands, latest passing exact-SHA code-review report, and 10/10 goal-verification report are committed and require no uncommitted wrapper or environment variable. CI evidence remains absent. -- Local vs CI consistency: no conflict observed, but the applicable CI arbiter has not run. + - The motivating audit, representative commands, latest passing exact-SHA code-review report, 10/10 goal-verification report, and adversarial report are committed and require no uncommitted wrapper or environment variable. +- Local vs CI consistency: no conflict observed; exact reviewed head `dfd14da` was green. ## Ledger / forks @@ -121,6 +122,10 @@ Adversarial review: - MEDIUM: skill parity is ambiguous under the pointer-based skill model. Remediated at `fb67648`; re-review pending. - MEDIUM: distributable release identity and transitive dependency identity are conflated. Remediated at `fb67648`; re-review pending. - MEDIUM: review/verification evidence and exact reviewed SHA were overstated. Claims were narrowed and exact-SHA code-review/verification reports are now branch-local; adversarial re-review pending. +- Re-review at `dfd14da`: `NOT-READY`. + - HIGH: qualification is ambiguous between one global coherent release set and journey-local support/withdrawal. + - LOW: checkpoint/base/CI wording was stale; corrected in this post-review record. +- Report: `planning/adr-0016-adversarial-dfd14da.md` Craft Review: @@ -137,7 +142,12 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until the remaining gauntlet completes. The draft PR does not authorize merge or ADR acceptance. +Choose the qualification unit: + +1. Global coherent release set — any mandatory-baseline failure disqualifies the set. +2. Journey-local — support can remain for unaffected journeys, requiring per-journey qualification semantics reconciled with one active manifest. + +The draft PR does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -149,8 +159,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Push this state-only update, wait for exact-head draft PR checks, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +After Jim chooses the qualification unit, revise the proposal and verification evidence, rerun code review and goal verification, push, wait for exact-head CI, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -Adversarial review of `ff9761a` returned NOT-READY. Its findings and subsequent lifecycle/pointer findings are remediated; code review passed at `481ca8c` and 10/10 goal verification passed at `9bd4f6f`. The proposal still needs adversarial re-review, Craft, clean-context, and CI. No implementation is authorized. +The first adversarial review's findings were remediated; code review passed at `481ca8c`, goal verification passed at `9bd4f6f`, and exact-head CI passed at `dfd14da`. Adversarial re-review at `dfd14da` found one remaining HIGH decision ambiguity. Craft and clean-context have not run. No implementation is authorized. From fb00f10b5620ce502345fdbdb1689ac7c0014d98 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 19:36:51 +0100 Subject: [PATCH 22/26] docs(adr): define journey-local release qualification - Keep one coherent active release set with journey-local support statuses\n- Define complete-route baseline, deterministic fallback, and parity rules --- ...eleased-truth-for-public-developer-docs.md | 125 ++++++++++++------ 1 file changed, 86 insertions(+), 39 deletions(-) diff --git a/adr/ADR-0016-released-truth-for-public-developer-docs.md b/adr/ADR-0016-released-truth-for-public-developer-docs.md index 4941a62..e068d87 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -7,7 +7,7 @@ - **Reviewers:** Jim Collinson - **Supersedes:** ADR-0003 (public source-selection default, verification-mode set, and HEAD-based freshness semantics for default public docs and skill only); ADR-0004 (default-public source resolution, staleness detection, and provenance-advance semantics only); ADR-0006 (conditions under which metadata-only provenance may advance for default public artifacts only); ADR-0013 (default-branch stamp-refresh interpretation for published-skill provenance only); ADR-0014 (source and conditions for pure public-skill provenance refresh only) - **Superseded by:** none -- **Related:** ADR-0005 through ADR-0007; ADR-0012 through ADR-0014; `planning/verification-workflow.md`; `planning/implementation-plan.md` §5; `planning/released-antd-v0.11.2-audit.md`; [WithAutonomi/ant-sdk issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233) +- **Related:** ADR-0005 through ADR-0007; ADR-0011 through ADR-0014; `planning/verification-workflow.md`; `planning/implementation-plan.md` §5; `planning/released-antd-v0.11.2-audit.md`; [WithAutonomi/ant-sdk issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233) ## Context @@ -37,18 +37,30 @@ The existing `target-manifest` mode can pin a release-hardening pass, but ADR-00 3. **Make released truth the public default and retain a distinct target mode for explicit pre-release hardening or versioned previews.** Chosen because it keeps the public contract honest while preserving preparation for the next release. 4. **Treat release status and public availability as sufficient evidence of usability.** Rejected because an obtainable release can expose a defective or nonfunctional route. Release status proves availability, not that the documented capability works. 5. **Allow each documentation surface to select released refs independently.** Rejected because independent pins cannot establish cross-component or deployed-network compatibility. The public surface needs one auditable release set. +6. **Require every public interface and journey to pass before a release set qualifies.** Rejected because an isolated defect would withdraw unaffected, evidence-backed interfaces even when the set still supplies every mandatory core outcome through complete routes. +7. **Qualify journeys locally within one coherent active release set, with a global mandatory-outcome baseline and global set fallback.** Chosen because it preserves unaffected journeys without permitting mixed versions or per-journey release fallback. ## Decision -Public rendered developer documentation and the published developer skill will describe **released truth** by default: the newest coherent release set that passes the mandatory public-baseline evidence below. The release set must be publicly obtainable through documented standard routes, compatible with its shipped dependencies and the deployed Autonomi Network for the claims made, and supported by capability-specific evidence. +Public rendered developer documentation and the published developer skill will describe **released truth** by default: one coherent active release set with journey-local qualification. A release set becomes active only when it passes the global release-set qualification layer, including the mandatory core-user-outcome baseline. Within that set, each developer journey receives its own evidence-backed status. + +### One default-public state + +There is exactly one default-public `released-truth` manifest. + +- When a supported baseline exists, the manifest names exactly one active coherent release set. Every interface and journey uses the component identities in that set. +- When no eligible coherent set qualifies, the manifest records `no-supported-baseline` and names no supported release set. +- The public state never has per-journey incumbents, mixed release versions, or a journey that falls back to a component from an older or different set. +- An older-set fallback is global: it replaces the active set for every journey. +- `target-manifest` previews remain separate from the default-public state and cannot supply a fallback for any default-public journey. ### Verification modes and authorities The verification model will retain exact per-surface provenance while changing its default: -- **`released-truth` is the default mode for public rendered documentation and the published developer skill.** Verification resolves every documented surface to exact refs in one machine-readable active released-truth manifest. +- **`released-truth` is the default mode for public rendered documentation and the published developer skill.** Verification resolves every documented surface to exact refs in the single default-public released-truth manifest. - **The release manifest represents a coherent product set, not a bag of latest tags.** Component versions, transitive refs that carry documented behavior, and deployed Autonomi Network compatibility must agree for the claims that depend on them. -- **The active released-truth manifest is the sole mutable machine-readable authority for active public release identities and capability support statuses.** Each promotion leaves an immutable promotion record as the evidence for why that manifest state was selected. Verification records and skill metadata identify the exact sources audited for their surfaces, but do not independently select a different active release or support status. +- **The active released-truth manifest is the sole mutable machine-readable authority for active public release identities and journey support statuses.** Each promotion leaves an immutable promotion record as the evidence for why that manifest state was selected. Verification records and skill metadata identify the exact sources audited for their surfaces, but do not independently select a different active release or support status. - **`target-manifest` remains an explicit pre-release, launch-hardening, or release-candidate mode.** It does not become the current public developer surface before release. If target content is published, it must be isolated and clearly labeled as a versioned preview rather than replacing the default docs. - **`current-merged-truth` is retired as a verification mode for public rendered documentation and the published skill.** Moving default branches remain research inputs for drift detection, impact assessment, and next-release preparation. A merge can open an audit queue; it cannot silently advance rendered prose or verification SHAs. @@ -58,51 +70,72 @@ An independently obtainable component is eligible for a `released-truth` candida A transitive shipped dependency has a different identity contract. It records the exact locked ref and an inspectable dependency path from the parent distributable release. It needs its own stable or general-availability release URL only when the public guidance presents it as independently obtainable. A transitive ref proves what a parent release shipped; it never by itself establishes that the dependency is independently installable or eligible as a released-truth candidate. -### Deterministic lifecycle and symmetric qualification +### Two qualification layers and complete routes + +Qualification has two layers, evaluated in this order for each coherent candidate set: + +1. **Journey qualification.** A journey has a stable identifier formed from `(interface, capability, material operation)`. Runtime and other journey evidence is keyed by that identifier. Each journey is classified as `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred` within the candidate set. Missing mandatory evidence fails that journey; it cannot be inferred from source or schema presence. `supported-with-known-limitation` counts as qualified only inside a proven safe and reproducible boundary. +2. **Global release-set qualification.** The set must have stable or general-availability distributable identities, clean obtainability through every route presented as standard, provenance integrity, no artifact-wide safety or security disqualifier, coherent shipped dependencies, an identifiable compatible deployed Autonomi Network state for network-dependent claims, and a passing mandatory core-user-outcome baseline. + +A **complete route** is a predeclared required set and sequence of qualified journeys under one approved interface, one coherent release set, and one compatible deployed-network state. Every required step must be `supported` or safely and reproducibly `supported-with-known-limitation`. Combining store through one interface with retrieve through another, or otherwise patching steps across interfaces, does not form a complete route and cannot pass an outcome. + +The mandatory core-user-outcome baseline is committed and reviewed before candidate evaluation. It declares the mandatory outcomes and the approved complete-route shapes that may satisfy each outcome. At least one complete route must pass for every mandatory outcome. At minimum, one approved interface must complete store and retrieve end to end on the same candidate set and compatible network state. The baseline does not require every public interface to pass. Mandatory outcomes and route inventory beyond this minimum remain a separately reviewed baseline-policy detail for the later specification and plan. + +Only qualified journeys and complete routes may be default or recommended. A `supported-with-known-limitation` journey may be default or recommended only within its proven safe and reproducible boundary. `unavailable` and `deferred` journeys cannot be default or recommended. + +### Deterministic lifecycle and requalification Candidate discovery reads canonical stable or general-availability publication state, independently of default-branch movement and prior watch-state observations. A stable release remains discoverable even when its source commit was already observed on a default branch before publication. Eligible coherent release sets are ordered by a deterministic component-wise partial order. One set dominates another only when it is not older for every component under the component's immutable canonical release ordering and is newer for at least one component. A committed, predeclared, reviewed total extension with a fixed component-identity order and immutable release-identity tie-breakers extends that partial order across **all** eligible coherent release sets, not only the maximal non-dominated sets, and produces one newest-first candidate order. The incumbent is placed in that same order by its immutable release identities as the current baseline, including when changed inputs will disqualify it. Every promotion or requalification decision evaluates the ordered candidates and incumbent against all applicable qualification and promotion requirements and selects the first qualifying set. A failed maximal set does not stop evaluation: evaluation continues through the remaining maximal sets and then through older or dominated eligible sets until one qualifies or the sequence is exhausted. -The existing incumbent participates in every decision as the current baseline and is requalified against the same inputs as the candidates. If it remains qualified, it is the first qualifying set unless a candidate that is strictly preferred under the committed total extension qualifies before it; a candidate at the same or a lower position cannot replace it. If the incumbent is disqualified, ordered evaluation continues until the first qualifying eligible set, including a set older than the former incumbent, is found. The selected set becomes the incumbent for later decisions, so a qualified incumbent cannot be displaced by an equally or less-preferred set and the fallback cannot create a downgrade loop. +For each set in that order, qualification first derives the complete journey-status matrix from one committed input snapshot and then applies global release-set qualification. The first globally qualifying set is selected. Discovery order, audit scheduling, and evidence-completion order cannot reorder evaluation or choose the result. + +The incumbent is one global release set, not a collection of journey incumbents. It is requalified against the same journey and global requirements as every candidate. If it remains globally qualified, it stays active unless a strictly preferred candidate qualifies before it. A candidate at the same or a lower position cannot replace it. A strictly preferred candidate may promote despite an explicit regression in a non-baseline journey only when the manifest, rendered docs, and published skill atomically remove the affected recommendation and publish the journey's honest status, limitation, and alternative before promotion completes. Until that cross-surface downgrade is complete, the promotion has not passed. The selected set becomes the incumbent for later decisions, so a qualified incumbent cannot be displaced by an equally or less-preferred set and fallback cannot create a downgrade loop. -Candidate and incumbent qualification is symmetric. Both must independently pass applicable obtainability, provenance-integrity, safety and security, deployed-network identity and compatibility, and mandatory public-baseline requirements. A decision uses one committed snapshot of qualification inputs; discovery order, audit scheduling, and evidence-completion order cannot reorder evaluation or choose the result. Missing mandatory evidence fails qualification for that decision. Exact snapshot, enumeration, and comparator mechanics belong in the later specification. +Promotion is not permanent. Every qualification-input change requalifies the affected journeys first, even when there is no new candidate, and then recomputes global release-set qualification. Triggers include artifact obtainability, withdrawal, or mutable-alias target movement; provenance-integrity evidence; applicable safety or security evidence; the mandatory core-outcome baseline definition or any complete-route result; newly discovered runtime or journey evidence; shipped-dependency identity, provenance, or compatibility evidence; and deployed-network identity or compatibility. A baseline-policy change remains a separate reviewed change and triggers requalification after approval. Default-branch movement alone neither qualifies nor disqualifies a candidate or incumbent unless it supplies changed evidence for one of these qualification inputs. -Promotion is not permanent. The incumbent is requalified during every promotion decision and whenever **any** qualification input changes, even when there is no new candidate. Triggers include artifact obtainability, withdrawal, or mutable-alias target movement; provenance-integrity evidence; applicable safety or security evidence; the mandatory public-baseline definition or any baseline result; newly discovered runtime or capability evidence that can affect a supported journey; shipped-dependency identity, provenance, or compatibility evidence; and deployed-network identity or compatibility. A mandatory-baseline policy change remains a separate reviewed change and triggers requalification after approval. Default-branch movement alone neither qualifies nor disqualifies a candidate or incumbent unless it supplies changed evidence for one of these qualification inputs. +Artifact-wide and journey-local failures have different effects: -Artifact-wide disqualifiers and capability-local defects have different scope. Withdrawal or unobtainability, failed provenance integrity, an artifact-wide safety or security failure, or incompatible deployed-network behavior disqualifies the artifact for every affected journey. A defect confined to a non-baseline capability may leave the rest of a qualified release set active when the affected capability is classified honestly and its remaining guidance is safe. If changed qualification evidence does not establish its scope, qualification fails closed for every plausibly affected journey until the scope is established. +- Withdrawal or unobtainability of a required artifact, failed provenance integrity, an artifact-wide safety or security failure, an issue whose possible artifact-wide scope cannot be ruled out, incompatible deployed-network behavior, or loss of the final complete route for any mandatory outcome fails global qualification. +- A defect proven to be isolated to one or more journeys changes those journey statuses. If its precise journey scope remains uncertain but artifact-wide impact has been ruled out, every plausibly affected journey fails closed until the scope is established. +- An isolated journey failure can remain local, including failure of a journey that participated in a previously passing baseline route, when another approved complete route in the same active set still satisfies that mandatory outcome. +- If the active set fails global qualification, deterministic selection evaluates all eligible coherent sets in newest-first order. Selecting an older set replaces the release set for every journey; no journey remains on the newer set. +- The manifest records global `no-supported-baseline` only after all eligible coherent sets are exhausted and none supplies every mandatory outcome through the required complete routes. It must not fall back to moving source, a prerelease, a `target-manifest` preview, or an unevaluated artifact. -If no eligible set qualifies and no incumbent remains qualified, the public surface has no supported baseline. It must not fall back to moving source, a prerelease, or any unevaluated artifact. Affected guidance is narrowed or withdrawn and states that no supported baseline exists. +For example, if the SDK store journey fails but a CLI complete store-and-retrieve route still passes on the same active set and network state, SDK store becomes `unavailable` or `deferred` and is no longer recommended. CLI remains `supported`, the release set remains globally qualified, and the public surface does not fall back to an older SDK release. ### Promotion evidence Every candidate release set requires a committed, machine-readable release manifest and an inspectable promotion record. Promotion fails closed if any mandatory field or evidence is absent. The record must contain, at minimum: -- **Immutable release identity:** the public stable or general-availability distributable identity for every independently obtainable component, including canonical publication state and URL or registry identity, immutable tag object and peeled source commit where applicable, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable; plus the exact locked ref and inspectable parent path for each transitive shipped dependency that carries documented behavior. +- **Immutable release identity and provenance integrity:** the public stable or general-availability distributable identity for every independently obtainable component, including canonical publication state and URL or registry identity, immutable tag object and peeled source commit where applicable, artifact names and checksums, publication timestamp, and the standard installation identity for every interface presented as installable; plus the exact locked ref and inspectable parent path for each transitive shipped dependency that carries documented behavior. - **Clean obtainability:** a successful installation of each documented standard installation route in a fresh supported environment. Every clean-install check and every default, supported, or recommended command uses an immutable version or digest selector, and the evidence records the exact immutable identity obtained rather than only the command text. The check must prove that the package, binary, container, or source-install identity resolves to the intended Autonomi artifact and version; source-directory presence and an unrelated registry name do not pass. A mutable alias may be mentioned only as an explicitly unsupported, non-authoritative informational convenience alongside the exact immutable target observed. It cannot establish support and is never a default, supported, or recommended installation command. Movement of its target triggers requalification of whether the informational mention remains accurate, but successful requalification cannot promote the alias into a default, supported, or recommended route. - **Release-set compatibility and deployed-network identity:** locked dependency evidence for the shipped set and, for network-dependent claims, the network environment, observation date, protocol or configuration anchor, and the most precise inspectable deployment identity available. If the deployed state cannot be identified precisely enough to reproduce a claim, that claim remains unverified and cannot be promoted. -- **Capability and runtime evidence:** a matrix mapping each public interface, capability, and material operation to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. -- **Known limitations and alternatives:** known defects, affected versions and operations, upstream issue links for material defects, and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when the supported usage remains safe and reproducible; otherwise the capability is `unavailable` or `deferred`. -- **Cross-surface consistency:** the public docs and published developer skill must map the enumerable coverage set defined below to the same support status, known defect or limitation, and safe alternative. Matching refs alone is insufficient. A mismatch blocks promotion. -- **Objective supported-baseline retention:** the incumbent supported release set, the deterministic newest-first order of all eligible coherent release sets, every evaluated set's result against all qualification and promotion requirements and the predeclared mandatory public baseline, and the resulting select, retain, or no-supported-baseline outcome. Failed maximal sets remain in the record before evaluation continues to older or dominated sets. A candidate replaces a qualified incumbent only when it is strictly preferred and every mandatory promotion requirement passes. The incumbent remains the supported default only for journeys where it continues to satisfy applicable obtainability, provenance-integrity, safety and security, shipped-dependency, deployed-network compatibility, and mandatory-baseline requirements. A disqualified incumbent cannot be retained. If the ordered sequence contains no qualifying set and no incumbent remains qualified, affected guidance is narrowed or withdrawn, and public guidance explicitly states that no supported baseline exists for that journey until a released candidate passes. +- **Journey and runtime evidence:** a matrix keyed by stable journey identifier, mapping each covered `(interface, capability, material operation)` to its evidence and one of `supported`, `supported-with-known-limitation`, `unavailable`, or `deferred`. Source and schema inspection can establish contract existence, but cannot establish a runnable journey. Installation claims require clean-install evidence; getting-started and how-to claims require the complete documented journey to run; network-dependent behavior requires execution against the identified compatible network state. +- **Safety, limitations, and alternatives:** artifact-wide and journey-local safety and security evidence; known defects, affected versions and operations; upstream issue links for material defects; and a verified safe alternative where one exists. `supported-with-known-limitation` is permitted only when every required use remains safe and reproducible inside the stated boundary; otherwise the journey is `unavailable` or `deferred`. +- **Cross-surface consistency:** the manifest, public docs, and published developer skill must agree for every covered journey on status, known defect or limitation, safe alternative, and recommendation state. Matching refs alone is insufficient. A mismatch blocks promotion or requalification publication. +- **Objective selection:** the deterministic newest-first order of all eligible coherent release sets, each set's journey-status matrix and global qualification result, the complete routes that pass each mandatory outcome, the selected, retained, or `no-supported-baseline` result, and every explicit journey regression. Failed maximal sets remain in the record before evaluation continues to older or dominated sets. -The mandatory public baseline is committed and reviewed before a candidate audit; changing it is a separate reviewed policy change, not part of producing promotion evidence. It includes, at minimum, a clean standard installation plus successful store and retrieve journeys for every interface the public docs present as the default or recommended way to use Autonomi. A safe alternative may preserve a non-baseline capability, but it cannot waive a mandatory baseline failure. Subject to the incumbent qualification rule above, the prior supported release set remains the default until a strictly preferred candidate passes every promotion requirement. When a newer available release is unsuitable and the incumbent remains qualified, installation and version guidance must name both that newer release and the older supported baseline, explain the affected boundary, and give the supported install command with an immutable version or digest selector; retaining an older baseline through stale metadata, a mutable default selector, or omission is prohibited. When the incumbent is disqualified, the affected guidance must instead narrow or withdraw the journey and state that no supported baseline exists until an eligible released set passes. +The baseline is outcome-based, not an every-interface pass requirement. A safe alternative or a second complete route can preserve a mandatory outcome, but cross-interface patchwork cannot. Subject to the selection rule above, the prior active release set remains the default until a strictly preferred candidate passes global qualification and every promotion requirement. When a newer available release fails global qualification and the incumbent remains qualified, installation and version guidance must name both the newer release and the older active baseline, explain the affected boundary, and give the supported install command with an immutable version or digest selector. Retaining an older set through stale metadata, a mutable default selector, or omission is prohibited. -### Capability truth and skill parity +### Journey truth and skill parity -Released truth is capability-specific and evidence-based: +Released truth is journey-specific within the one active release set: -- “Usable” does not mean “bug-free.” A known defect is part of released truth. The docs must state the affected route, boundary, or operation and provide a safe alternative when one exists. -- A broken or unproven route must not be presented as working. Missing evidence requires the page to defer, narrow, stub, or reframe the claim rather than infer success. +- “Usable” does not mean “bug-free.” A known defect is part of released truth. The docs must state the affected journey, boundary, or operation and provide a safe alternative when one exists. +- A broken or unproven journey must not be presented as working. Missing evidence requires the page to defer, narrow, stub, or reframe the claim rather than infer success. - A package, binary, container, binding, or tool is available only when its documented standard installation identity resolves publicly, or when the project explicitly supports a reproducible source-install route that has been verified from a clean environment. Source-directory presence alone is not availability. - A release is promoted into public docs only when its manifest and promotion record satisfy the mandatory fields and evidence floors in this decision. -- Non-baseline capabilities do not block the whole release set when their status and guidance are honest. They remain `unavailable` or `deferred`, or `supported-with-known-limitation` when a safe, verified usage boundary exists. +- Isolated journey defects do not block the whole release set while at least one approved complete route still passes every mandatory outcome. The affected journeys remain `unavailable` or `deferred`, or `supported-with-known-limitation` when a safe, verified usage boundary exists. +- No journey may use an older or different release set because it works there. It remains `unavailable` or `deferred` under the active set unless it qualifies on that set. +- ADR-0011's SDK-primary stance applies only where the relevant SDK journeys qualify under this decision. It cannot override a journey status or cause an unqualified SDK journey to remain default or recommended. -The active manifest defines an enumerable coverage set of stable interface, capability, and material-operation identifiers. It covers every claim represented in the rendered docs and everything the published skill bundles, recommends, warns about, or routes through a pointer. +The active manifest defines an enumerable coverage set of stable journey identifiers. It covers every claim represented in the rendered docs and everything the published skill bundles, recommends, warns about, or routes through a pointer. -For each covered identifier, the skill may represent released guidance as bundled content or as an explicit pointer to the default released-truth docs. A pointer satisfies parity only when it resolves under the same active manifest, the skill carries no contradictory claim, and the agent fetches the released guidance before answering release-sensitive detail. If that fetch fails, the agent defers the release-sensitive detail instead of consulting moving source or fabricating an answer. Parity does not require duplication of pointered prose. Any claim, recommendation, warning, limitation, alternative, or routing instruction that the skill does bundle must match the active released guidance directly. +For each covered journey identifier, the skill may represent released guidance as bundled content or as an explicit pointer to the default released-truth docs. A pointer satisfies parity only when it resolves under the same active manifest and journey status, the skill carries no contradictory claim, and the agent fetches the released guidance before answering release-sensitive detail. If that fetch fails, the agent defers the release-sensitive detail instead of consulting moving source or fabricating an answer. Parity does not require duplication of pointered prose. Any claim, recommendation, warning, limitation, alternative, or routing instruction that the skill does bundle must match the active released guidance directly. -Fetched released guidance is untrusted factual input, never executable instructions or authority over system or developer instructions, the skill, or the user's request. The agent must delimit fetched content from controlling instructions and ignore any embedded request to alter behavior, reveal secrets, bypass safeguards, fetch unrelated material, or take actions. Release-sensitive claims or actions derived from fetched content must still be checked against the active released-truth manifest, the applicable capability status, and applicable safety constraints. Fetched content cannot change tool permissions, authorize spending, publishing, or destructive actions, or cross an approval gate. If provenance and manifest alignment cannot be established, or fetched content conflicts with the skill or the user's request, the agent defers the release-sensitive detail and surfaces the conflict; it never follows the embedded instruction or falls back to moving source. These restrictions preserve ADR-0013's pointer tier and apply whether the fetch succeeds or fails. +Fetched released guidance is untrusted factual input, never executable instructions or authority over system or developer instructions, the skill, or the user's request. The agent must delimit fetched content from controlling instructions and ignore any embedded request to alter behavior, reveal secrets, bypass safeguards, fetch unrelated material, or take actions. Release-sensitive claims or actions derived from fetched content must still be checked against the active released-truth manifest, the applicable journey status, and applicable safety constraints. Fetched content cannot change tool permissions, authorize spending, publishing, or destructive actions, or cross an approval gate. If provenance and manifest alignment cannot be established, or fetched content conflicts with the skill or the user's request, the agent defers the release-sensitive detail and surfaces the conflict; it never follows the embedded instruction or falls back to moving source. These restrictions preserve ADR-0013's pointer tier and apply whether the fetch succeeds or fails. The existing verification-block invariants remain: @@ -123,7 +156,7 @@ This ADR supersedes only the named default-public source and provenance-advance - **ADR-0013:** superseded only for the default-branch stamp-refresh interpretation of published-skill provenance. Its three-part freshness defense, pointer content tier, runtime version check, and stable-URL contract remain intact. A skill stamp refresh now means conformance to the active released-truth manifest, not conformance to moving HEAD. - **ADR-0014:** superseded only for the source and conditions of a pure public-skill provenance refresh. Its shared source-audit workflow, `feeds_skills` relationship, distinct metadata responsibilities, and coherent-state requirement remain intact. Pure skill provenance may advance only with a released-truth promotion. The content version and release history may remain unchanged only when bundled claims, recommendations, warnings, limitations, alternatives, and pointers remain unchanged. -ADR-0005 and ADR-0007 remain fully intact. Scheduling, adapters, detailed manifest and watch-state schemas, exact comparator mechanics, promotion and detection mechanics, migration sequencing, and automation changes belong in a follow-up specification and plan. +ADR-0005, ADR-0007, and ADR-0011 remain intact. ADR-0011's interface stance is constrained only by the evidence-backed recommendation rule above. Detailed journey-identifier schema, route membership and sequencing, dependency mapping, propagation and atomic-publication mechanics, adapters, scheduling, baseline inventory beyond the minimum, detailed manifest and watch-state schemas, exact comparator mechanics, promotion and detection mechanics, migration sequencing, and automation changes belong in a follow-up reviewed specification and plan. ## Consequences @@ -132,6 +165,7 @@ ADR-0005 and ADR-0007 remain fully intact. Scheduling, adapters, detailed manife - Public docs describe what developers can obtain and build against rather than what unreleased source suggests. - Release, dependency, network, package, and runtime compatibility become one auditable contract. - Known defects produce actionable guidance and upstream feedback instead of false confidence. +- Isolated journey defects preserve unaffected interfaces when another complete route continues to satisfy the mandatory outcome. - Moving source remains monitored without silently changing the public product story. - Exact provenance, fail-closed behavior, and the source-audit discipline from ADR-0003 are preserved. @@ -140,15 +174,20 @@ ADR-0005 and ADR-0007 remain fully intact. Scheduling, adapters, detailed manife - Documentation can intentionally lag merged source until a release is promoted. - Maintaining a coherent manifest across multiple repositories and deployed-network dependencies adds release-management work. - If promotion or incumbent requalification is neglected, public docs can become stale even while source-movement detection is working. -- Capability-specific evidence and known-defect guidance require continuing judgment and maintenance. +- Journey-specific evidence and known-defect guidance require continuing judgment and maintenance. - Some source-present bindings or APIs will remain undocumented as supported until an obtainable, verified route exists. +- A newer qualifying set can regress an optional journey after its recommendation is atomically withdrawn and its status is published honestly. +- There is no old-release fallback for one failed journey; a journey that works only on an older set remains unavailable under the active newer set. +- Stable journey identifiers, complete-route dependency mapping, and atomic manifest/docs/skill updates add policy and implementation complexity. ### Neutral / Operational - Default-branch movement still matters: it starts impact assessment and prepares future documentation, but does not itself change released truth. - Versioned previews may describe a target release when clearly separated from the default public docs. +- Journey status may change without changing the active release-set identity. +- `unavailable` and `deferred` are journey-local states; `no-supported-baseline` is a global public state. - Accepted ADRs remain immutable; this ADR's `Supersedes` field is the authoritative supersession link if this proposal is accepted. -- The exact release-manifest shape, comparator, migration from existing modes, release-promotion workflow, and automation updates require a separate reviewed specification and execution plan. +- The deferred mechanics and inventories named above require a separate reviewed specification and execution plan. ## Validation @@ -160,30 +199,38 @@ This decision is satisfied when all of the following remain true: - Shuffling API, registry, or filesystem discovery results does not change the eligible sets, the newest-first order over all eligible sets, or the selection outcome. - Incomparable sets resolve identically through the committed total extension and its fixed component order and immutable release-identity tie-breakers; after each failed maximal set, evaluation continues in that order through older or dominated sets and selects the first qualifying set. - Replaying the same committed qualification-input snapshot with a different audit schedule or evidence-completion order produces the same evaluation order and selected, retained, or no-supported-baseline outcome. -- Every public verification record resolves to exact refs in one coherent release manifest, including shipped dependency refs where they carry documented behavior. -- Every release promotion record contains all seven minimum evidence groups required by this decision and identifies the predeclared mandatory public baseline. -- Candidate and incumbent qualification apply the same obtainability, provenance-integrity, safety and security, deployed-network compatibility, and mandatory-baseline requirements. -- Changing any qualification input requalifies the incumbent without requiring a new candidate. Validation changes each trigger class independently: obtainability or alias target; provenance integrity; safety or security evidence; an approved mandatory-baseline definition or a baseline result; runtime or capability evidence that can affect a supported journey; shipped-dependency evidence; and deployed-network identity or compatibility. -- A plausibly journey-affecting qualification-input change with uncertain scope fails closed for every plausibly affected journey until its scope is established. +- Exactly one default-public manifest names exactly one active coherent release set, or records `no-supported-baseline` and names no supported set. Every public verification record resolves to that state, including shipped dependency refs where they carry documented behavior. +- Every release promotion record contains all seven minimum evidence groups required by this decision and identifies the predeclared mandatory core-user-outcome baseline. +- For each eligible set in deterministic newest-first order, the journey-status matrix is derived before global qualification, and the first globally qualifying set is selected. +- Candidate and incumbent qualification apply the same stable or general-availability identity, clean-obtainability, provenance-integrity, artifact-wide safety and security, coherent-dependency, deployed-network compatibility, and mandatory core-outcome requirements. +- Changing any qualification input requalifies affected journeys before recomputing the incumbent's global qualification, without requiring a new candidate. Validation changes each trigger class independently: obtainability or alias target; provenance integrity; safety or security evidence; an approved baseline definition or a complete-route result; runtime or journey evidence; shipped-dependency evidence; and deployed-network identity or compatibility. +- An artifact-wide issue, or uncertainty about whether an issue is artifact-wide, disqualifies the set globally. When artifact-wide impact is ruled out but journey scope remains uncertain, every plausibly affected journey fails closed until its scope is established. - A mutable alias, if mentioned, is explicitly unsupported and non-authoritative and appears alongside the exact immutable target observed; it is never a default, supported, or recommended installation command. - Moving a mentioned mutable alias to a different immutable target requalifies whether the informational mention remains accurate; successful requalification cannot establish support or promote the alias into a default, supported, or recommended route. - Claims that depend on deployed Autonomi Network behavior are checked against the identified compatible deployed state; claims without a reproducible deployment anchor remain unverified. - Getting-started and how-to journeys have complete runtime evidence for the released interface they recommend; source or schema inspection alone does not pass. +- At least one predeclared complete route passes every mandatory outcome, including an end-to-end store-and-retrieve route under one approved interface on the same release set and network state. +- A store step from one interface and a retrieve step from another cannot be combined to pass a complete route. +- If SDK store fails while a CLI complete store-and-retrieve route passes on the same active set, SDK store is `unavailable` or `deferred` and not recommended, CLI remains `supported`, and the set remains globally qualified. +- An isolated MCP or other non-baseline journey failure remains local when every mandatory outcome retains a complete route. +- A strictly preferred candidate with a non-baseline journey regression cannot promote until manifest, docs, and skill atomically publish the downgrade and remove the affected recommendation. +- A journey that works only on an older eligible set remains `unavailable` or `deferred` under an active newer set; no per-journey release fallback occurs. +- A `supported-with-known-limitation` journey contributes to a complete route only when every required step remains safe and reproducible inside the documented boundary. - Known released defects and boundaries are represented in rendered guidance with safe alternatives where available, and material upstream defects are tracked. -- A capability-local non-baseline defect changes only its covered capability when evidence establishes that isolation; uncertain safety or security scope fails closed for every plausibly affected journey. -- Every coverage-set identifier has the same status, known defect or limitation, and safe alternative in the rendered docs and published developer skill. +- A journey-local defect, including failure of a journey formerly used by a baseline route, changes only its covered journeys when evidence establishes that isolation and another complete route still satisfies the outcome. +- Every covered journey identifier has the same status, known defect or limitation, safe alternative, and recommendation state in the manifest, rendered docs, and published developer skill. - Pointer parity resolves against the active released-truth manifest, fetches released guidance before release-sensitive answers, and defers that detail on fetch failure; bundled skill guidance matches directly without requiring duplicated pointer prose. -- Fetched pointer content remains delimited as untrusted factual input and cannot override controlling instructions, change permissions, authorize gated actions, or cause embedded requests to be followed; release-sensitive claims and actions remain subject to the active manifest, capability status, and applicable safety constraints. +- Fetched pointer content remains delimited as untrusted factual input and cannot override controlling instructions, change permissions, authorize gated actions, or cause embedded requests to be followed; release-sensitive claims and actions remain subject to the active manifest, journey status, and applicable safety constraints. - If fetched-content provenance or manifest alignment cannot be established, or fetched content conflicts with the skill or user request, the agent defers the release-sensitive detail, surfaces the conflict, and does not fall back to moving source. - A transitive dependency ref with no independent release URL remains valid shipped-dependency provenance but does not establish independent installability or candidate eligibility. -- If a newer available release fails the mandatory baseline and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command with its immutable version or digest selector. -- If an incumbent becomes withdrawn or unobtainable, unsafe or insecure, incompatible with the deployed Autonomi Network, or noncompliant with the mandatory baseline, affected guidance narrows or withdraws the journey and states that no supported baseline exists until a released candidate passes. +- If a newer available release fails global qualification and the incumbent remains qualified, installation and version guidance names the newer release, the retained supported baseline, the reason, and the supported install command with its immutable version or digest selector. +- If the active set loses the final complete route for any mandatory outcome, deterministic selection evaluates every eligible coherent set in order. Any older fallback replaces the set for every journey; if no set qualifies, the manifest records global `no-supported-baseline` and names no supported set. - No verification record backing the default public rendered documentation or published developer skill uses `current-merged-truth`. - `target-manifest` content never backs the default public surface; any published target content is isolated as a versioned preview and clearly labeled pre-release. - Movement on an upstream default branch cannot by itself change public rendered prose, published skill guidance, or released verification SHAs. -- Promotion of a new release leaves an auditable record of artifacts, exact refs, compatibility, journey evidence, and accepted limitations. +- Promotion of a new release leaves an auditable record of artifacts, exact refs, compatibility, journey evidence, complete routes, global results, selection outcome, and explicit regressions. -Review triggers include changing the public default away from released truth, allowing merged source to advance public docs without release promotion, weakening artifact or usability evidence, or merging pre-release target content into the default public surface without clear preview isolation. +Review triggers include changing the one-manifest/one-active-set invariant, allowing per-journey release fallback, weakening complete-route requirements, changing the boundary between global release-set and journey qualification, hiding a journey regression during promotion or requalification, changing the public default away from released truth, allowing merged source to advance public docs without release promotion, weakening artifact or usability evidence, or merging pre-release target content into the default public surface without clear preview isolation. ## Notes for AI-assisted work From b1e48469dc96928beb4ef6d9e04dd3a0acc04e9c Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 19:38:51 +0100 Subject: [PATCH 23/26] docs(gsd): record journey-local ADR decision --- planning/STATE.md | 11 +++++++---- planning/gsd-adr-0016-checkpoint.md | 19 ++++++++----------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index c23833d..0c047bb 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,14 +4,14 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: decide ADR-0016 qualification granularity -- Status: adversarial NOT-READY; attended decision checkpoint +- Task: re-review journey-local qualification amendment +- Status: Jim chose journey-local qualification; amendment committed and CI green; code review pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 - Branch point: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` - Current draft-PR base: `origin/main` at `487866a249fcb5ad7d8dd7829c017ed63d421343` -- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`; pointer-security correction `4873f368feec5183b7a69c493c86d2beb6efe8b5` +- Proposed ADR commits: initial `5716bbe539c352b7da880b3a0ad54dd3d475e546`; first remediation `735091d7ed55db90eb48129c879796dc6ebfe963`; second correction `57ec56cb90db89583603f4cf075c9f7d272a9b87`; adversarial remediation `fb67648a8ac0a874ea94a1e1c3e208490a052a8c`; lifecycle correction `9c2f1da15de685e54fdb0ef8eceeedfa2692f153`; pointer-security correction `4873f368feec5183b7a69c493c86d2beb6efe8b5`; journey-local amendment `fb00f10b5620ce502345fdbdb1689ac7c0014d98` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -56,6 +56,9 @@ - HIGH: the ADR simultaneously makes mandatory-baseline qualification global to one coherent release set and permits journey-local retention/withdrawal. One unit of qualification and fallback must be chosen. - LOW: state/checkpoint must distinguish the historical branch point from the current PR base and describe scope-gated CI checks honestly. - Craft and clean-context did not run because adversarial blocked advancement. +- Jim chose option 2 on 2026-08-20: one active coherent release set with journey-local support status, no mixed versions or per-journey old-release fallback, and global no-supported-baseline only when no eligible set supplies complete routes for every mandatory core outcome. +- Journey-local amendment `fb00f10` formalizes that decision, including same-interface complete routes, global set selection/fallback, atomic optional-journey regression disclosure, journey-keyed manifest/docs/skill parity, and the minimum end-to-end store-and-retrieve outcome. Local ADR governance and 20 tests passed; exact-head draft-PR CI and GitBook checks are green. +- Exact-head code review, goal verification, and adversarial re-review remain pending for `fb00f10`. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: draft PR #98. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks also returned success but were scope-gate no-ops for this branch, not substantive coverage. @@ -70,4 +73,4 @@ ## Next -- Jim must choose global release-set qualification or journey-local qualification reconciled with one active manifest. After that decision, revise the Proposed ADR and verification evidence, rerun code review, goal verification, CI, and adversarial before Craft and clean-context. Do not merge, accept the ADR, or begin implementation. +- Run exact-head code review and goal verification for the journey-local amendment, persist new reports, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 8e88afb..702c683 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,11 +8,11 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Stop for decision — exact-head CI is green, but adversarial review returned NOT-READY on qualification granularity. +Continue — Jim chose journey-local qualification within one coherent active release set; amendment `fb00f10` and exact-head CI are green, with re-review pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit blocked at adversarial decision finding -Unreviewed backlog if deferred: Craft and clean-context remain unrun because adversarial did not pass +Review cadence: per-unit re-review in progress +Unreviewed backlog if deferred: Craft and clean-context remain unrun until the amended proposal passes adversarial review ## What happened @@ -71,6 +71,7 @@ Results: - Pointer-security local validation at `4873f36`: ADR governance passed, 20 governance tests passed, and `git diff --check` passed. - Code review at exact commit `481ca8cb653b32823851d38b2bcc36b4007ddf7a`: passed with no findings. Full report: `planning/adr-0016-code-review-481ca8c.md`. - Goal verification at exact commit `9bd4f6f0780d3a431a134214f9abaa3fddb45ea4`: passed, 10/10 decision-contract goals verified with no gaps. Full report: `planning/adr-0016-verification-9bd4f6f.md`. +- Journey-local content amendment `fb00f10`: local ADR governance and 20 tests passed; exact-head ADR Governance and GitBook checks passed on draft PR #98. ## Honesty rules check @@ -126,6 +127,7 @@ Adversarial review: - HIGH: qualification is ambiguous between one global coherent release set and journey-local support/withdrawal. - LOW: checkpoint/base/CI wording was stale; corrected in this post-review record. - Report: `planning/adr-0016-adversarial-dfd14da.md` +- Owner disposition: Jim chose journey-local support within one active coherent release set. Amendment `fb00f10` resolves the ambiguity; adversarial re-review pending. Craft Review: @@ -142,12 +144,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -Choose the qualification unit: - -1. Global coherent release set — any mandatory-baseline failure disqualifies the set. -2. Journey-local — support can remain for unaffected journeys, requiring per-journey qualification semantics reconciled with one active manifest. - -The draft PR does not authorize merge or ADR acceptance. +No owner decision is pending until re-review completes. Jim's choice does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -159,8 +156,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -After Jim chooses the qualification unit, revise the proposal and verification evidence, rerun code review and goal verification, push, wait for exact-head CI, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Run exact-head code review and goal verification for `fb00f10`, persist their reports, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -The first adversarial review's findings were remediated; code review passed at `481ca8c`, goal verification passed at `9bd4f6f`, and exact-head CI passed at `dfd14da`. Adversarial re-review at `dfd14da` found one remaining HIGH decision ambiguity. Craft and clean-context have not run. No implementation is authorized. +The first adversarial findings were remediated; code review passed at `481ca8c`, goal verification passed at `9bd4f6f`, and CI passed. Adversarial re-review at `dfd14da` found one decision ambiguity; Jim chose journey-local qualification and amendment `fb00f10` implements it. Exact-head re-review, Craft, and clean-context remain. No implementation is authorized. From 39e2cdff010a5ef729f2d655b29ef684a3c0118f Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 19:44:49 +0100 Subject: [PATCH 24/26] docs(gsd): record journey-local code review --- planning/STATE.md | 9 +++--- planning/adr-0016-code-review-b1e4846.md | 38 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 9 ++++-- 3 files changed, 49 insertions(+), 7 deletions(-) create mode 100644 planning/adr-0016-code-review-b1e4846.md diff --git a/planning/STATE.md b/planning/STATE.md index 0c047bb..136e5cf 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: re-review journey-local qualification amendment -- Status: Jim chose journey-local qualification; amendment committed and CI green; code review pending +- Task: verify journey-local qualification amendment +- Status: journey-local code review passed; goal verification pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -58,7 +58,8 @@ - Craft and clean-context did not run because adversarial blocked advancement. - Jim chose option 2 on 2026-08-20: one active coherent release set with journey-local support status, no mixed versions or per-journey old-release fallback, and global no-supported-baseline only when no eligible set supplies complete routes for every mandatory core outcome. - Journey-local amendment `fb00f10` formalizes that decision, including same-interface complete routes, global set selection/fallback, atomic optional-journey regression disclosure, journey-keyed manifest/docs/skill parity, and the minimum end-to-end store-and-retrieve outcome. Local ADR governance and 20 tests passed; exact-head draft-PR CI and GitBook checks are green. -- Exact-head code review, goal verification, and adversarial re-review remain pending for `fb00f10`. +- Exact-head goal verification and adversarial re-review remain pending for 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`. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: draft PR #98. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks also returned success but were scope-gate no-ops for this branch, not substantive coverage. @@ -73,4 +74,4 @@ ## Next -- Run exact-head code review and goal verification for the journey-local amendment, persist new reports, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Run exact-head goal verification for the journey-local amendment, persist the report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 702c683..427a665 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,7 +8,7 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — Jim chose journey-local qualification within one coherent active release set; amendment `fb00f10` and exact-head CI are green, with re-review pending. +Continue — journey-local code review passed at `b1e4846`; goal verification is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit re-review in progress @@ -46,6 +46,7 @@ Files changed/artifacts produced: - `planning/adr-0016-code-review-481ca8c.md` - `planning/adr-0016-verification-9bd4f6f.md` - `planning/adr-0016-adversarial-dfd14da.md` +- `planning/adr-0016-code-review-b1e4846.md` Checks run: @@ -72,6 +73,7 @@ Results: - Code review at exact commit `481ca8cb653b32823851d38b2bcc36b4007ddf7a`: passed with no findings. Full report: `planning/adr-0016-code-review-481ca8c.md`. - Goal verification at exact commit `9bd4f6f0780d3a431a134214f9abaa3fddb45ea4`: passed, 10/10 decision-contract goals verified with no gaps. Full report: `planning/adr-0016-verification-9bd4f6f.md`. - Journey-local content amendment `fb00f10`: local ADR governance and 20 tests passed; exact-head ADR Governance and GitBook checks passed on draft PR #98. +- Journey-local code review at `b1e4846`: passed with no findings; all global/journey truth-table scenarios passed. Report: `planning/adr-0016-code-review-b1e4846.md`. ## Honesty rules check @@ -128,6 +130,7 @@ Adversarial review: - LOW: checkpoint/base/CI wording was stale; corrected in this post-review record. - Report: `planning/adr-0016-adversarial-dfd14da.md` - Owner disposition: Jim chose journey-local support within one active coherent release set. Amendment `fb00f10` resolves the ambiguity; adversarial re-review pending. +- Independent code-review disposition at `b1e4846`: ambiguity resolved with no new findings. Craft Review: @@ -156,8 +159,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run exact-head code review and goal verification for `fb00f10`, persist their reports, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Run exact-head goal verification for `fb00f10`, persist its report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -The first adversarial findings were remediated; code review passed at `481ca8c`, goal verification passed at `9bd4f6f`, and CI passed. Adversarial re-review at `dfd14da` found one decision ambiguity; Jim chose journey-local qualification and amendment `fb00f10` implements it. Exact-head re-review, Craft, and clean-context remain. No implementation is authorized. +The first adversarial findings were remediated; adversarial re-review at `dfd14da` found one decision ambiguity. Jim chose journey-local qualification, amendment `fb00f10` implements it, and exact-head code review passed at `b1e4846`. Goal verification, adversarial re-review, Craft, and clean-context remain. No implementation is authorized. From ef646b9f7d360a5ef2597d3b77cfc08cedb5fd61 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 19:51:23 +0100 Subject: [PATCH 25/26] docs(gsd): record journey-local verification --- planning/STATE.md | 7 ++-- planning/adr-0016-verification-39e2cdf.md | 51 +++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 8 ++-- 3 files changed, 60 insertions(+), 6 deletions(-) create mode 100644 planning/adr-0016-verification-39e2cdf.md diff --git a/planning/STATE.md b/planning/STATE.md index 136e5cf..c187ac2 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: verify journey-local qualification amendment -- Status: journey-local code review passed; goal verification pending +- Task: adversarial re-review of journey-local qualification +- Status: journey-local code review and goal verification passed; adversarial pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -60,6 +60,7 @@ - Journey-local amendment `fb00f10` formalizes that decision, including same-interface complete routes, global set selection/fallback, atomic optional-journey regression disclosure, journey-keyed manifest/docs/skill parity, and the minimum end-to-end store-and-retrieve outcome. Local ADR governance and 20 tests passed; exact-head draft-PR CI and GitBook checks are green. - Exact-head goal verification and adversarial re-review remain pending for 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`. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` - CI arbiter: draft PR #98. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks also returned success but were scope-gate no-ops for this branch, not substantive coverage. @@ -74,4 +75,4 @@ ## Next -- Run exact-head goal verification for the journey-local amendment, persist the report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Push this verification record, confirm exact-head CI, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 427a665..509080a 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,7 +8,7 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — journey-local code review passed at `b1e4846`; goal verification is pending. +Continue — journey-local code review and 10/10 goal verification passed; adversarial re-review is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit re-review in progress @@ -47,6 +47,7 @@ Files changed/artifacts produced: - `planning/adr-0016-verification-9bd4f6f.md` - `planning/adr-0016-adversarial-dfd14da.md` - `planning/adr-0016-code-review-b1e4846.md` +- `planning/adr-0016-verification-39e2cdf.md` Checks run: @@ -74,6 +75,7 @@ Results: - Goal verification at exact commit `9bd4f6f0780d3a431a134214f9abaa3fddb45ea4`: passed, 10/10 decision-contract goals verified with no gaps. Full report: `planning/adr-0016-verification-9bd4f6f.md`. - Journey-local content amendment `fb00f10`: local ADR governance and 20 tests passed; exact-head ADR Governance and GitBook checks passed on draft PR #98. - Journey-local code review at `b1e4846`: passed with no findings; all global/journey truth-table scenarios passed. Report: `planning/adr-0016-code-review-b1e4846.md`. +- Journey-local 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`. ## Honesty rules check @@ -159,8 +161,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run exact-head goal verification for `fb00f10`, persist its report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Push the verification record, confirm exact-head CI, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -The first adversarial findings were remediated; adversarial re-review at `dfd14da` found one decision ambiguity. Jim chose journey-local qualification, amendment `fb00f10` implements it, and exact-head code review passed at `b1e4846`. Goal verification, adversarial re-review, Craft, and clean-context remain. No implementation is authorized. +The first adversarial findings were remediated; adversarial re-review at `dfd14da` found one decision ambiguity. Jim chose journey-local qualification, amendment `fb00f10` implements it, code review passed at `b1e4846`, and 10/10 goal verification passed at `39e2cdf`. Adversarial re-review, Craft, and clean-context remain. No implementation is authorized. From 5035e05154532dc6440b03b73a1527f67a076077 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Thu, 20 Aug 2026 20:03:52 +0100 Subject: [PATCH 26/26] docs(gsd): record ADR route-continuity blockers --- planning/STATE.md | 16 +++++-- planning/adr-0016-adversarial-ef646b9.md | 61 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 21 +++++--- 3 files changed, 86 insertions(+), 12 deletions(-) create mode 100644 planning/adr-0016-adversarial-ef646b9.md diff --git a/planning/STATE.md b/planning/STATE.md index c187ac2..868537e 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,8 +4,8 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: adversarial re-review of journey-local qualification -- Status: journey-local code review and goal verification passed; adversarial pending +- Task: remediate complete-route continuity and ADR-0011 supersession +- Status: adversarial NOT-READY; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -58,12 +58,18 @@ - Craft and clean-context did not run because adversarial blocked advancement. - Jim chose option 2 on 2026-08-20: one active coherent release set with journey-local support status, no mixed versions or per-journey old-release fallback, and global no-supported-baseline only when no eligible set supplies complete routes for every mandatory core outcome. - Journey-local amendment `fb00f10` formalizes that decision, including same-interface complete routes, global set selection/fallback, atomic optional-journey regression disclosure, journey-keyed manifest/docs/skill parity, and the minimum end-to-end store-and-retrieve outcome. Local ADR governance and 20 tests passed; exact-head draft-PR CI and GitBook checks are green. -- Exact-head goal verification and adversarial re-review remain pending for the journey-local amendment. +- Exact-head adversarial re-review remained pending after the journey-local amendment. - Exact-head code review at `b1e4846`: passed with no findings and all qualification truth-table scenarios passed. Report: `planning/adr-0016-code-review-b1e4846.md`. - Exact-head goal verification at `39e2cdf`: passed, 10/10 goals and all required truth-table scenarios verified with no gaps. Report: `planning/adr-0016-verification-39e2cdf.md`. +- Exact-head adversarial re-review at `ef646b9`: `NOT-READY`. Report: `planning/adr-0016-adversarial-ef646b9.md`. + - HIGH: top-level `SDK` continuity still permits incompatible bindings/transports to be combined into a false complete route. + - HIGH: allowing CLI to become the only recommended complete route changes ADR-0011's unconditional SDK-primary stance, so ADR-0011 must be precisely superseded rather than called intact. + - MEDIUM: branch-local truth-table evidence must include concrete binding, transport, installation, runtime/configuration, and carried-state identities. + - LOW: state/checkpoint/PR evidence was stale, and the historical v0.11.2 defect sentence needs past-tense scoping. +- Craft and clean-context did not run because adversarial blocked advancement. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` -- CI arbiter: draft PR #98. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks also returned success but were scope-gate no-ops for this branch, not substantive coverage. +- CI arbiter: draft PR #98. Exact reviewed head `ef646b9` passed ADR Governance and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. - Freshness risk: the imported v0.11.2 audit is explicitly historical; `antd` v0.12.0 has since released and issue #233 has closed. A fresh candidate-release audit is required before implementation, regardless of ADR acceptance. ## Constraints @@ -75,4 +81,4 @@ ## Next -- Push this verification record, confirm exact-head CI, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- With Jim's attended approval, add concrete complete-route continuity, precisely supersede ADR-0011's unconditional SDK-primary clause, scope the historical v0.11.2 sentence, and add inspectable concrete truth-table evidence; then rerun code review, verification, CI, and adversarial. Do not merge, accept the ADR, or begin implementation. 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/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 509080a..c5c5f87 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,11 +8,11 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Continue — journey-local code review and 10/10 goal verification passed; adversarial re-review is pending. +Revise — journey-local code review and goal verification passed, but adversarial re-review found route-continuity and ADR-0011 blockers. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. -Review cadence: per-unit re-review in progress -Unreviewed backlog if deferred: Craft and clean-context remain unrun until the amended proposal passes adversarial review +Review cadence: per-unit blocked at adversarial review +Unreviewed backlog if deferred: Craft and clean-context remain unrun because adversarial did not pass ## What happened @@ -27,7 +27,7 @@ No implementation, rendered documentation, skill, manifest, automation, CI, test CI arbiter / green of record: - Location: `.github/workflows/adr-governance.yml`, triggered by pull requests that change `adr/**`. -- Status: draft PR #98 is open. Exact reviewed head `dfd14da` passed ADR Governance and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. +- Status: draft PR #98 is open. Exact reviewed head `ef646b9` passed ADR Governance and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. Local fast gate / `.gsd/gate.sh`: @@ -48,6 +48,7 @@ Files changed/artifacts produced: - `planning/adr-0016-adversarial-dfd14da.md` - `planning/adr-0016-code-review-b1e4846.md` - `planning/adr-0016-verification-39e2cdf.md` +- `planning/adr-0016-adversarial-ef646b9.md` Checks run: @@ -133,6 +134,12 @@ Adversarial review: - Report: `planning/adr-0016-adversarial-dfd14da.md` - Owner disposition: Jim chose journey-local support within one active coherent release set. Amendment `fb00f10` resolves the ambiguity; adversarial re-review pending. - Independent code-review disposition at `b1e4846`: ambiguity resolved with no new findings. +- Re-review at `ef646b9`: `NOT-READY`. + - HIGH: a top-level SDK route can still combine incompatible bindings or transports. + - HIGH: ADR-0016 changes ADR-0011's unconditional SDK-primary stance but does not supersede it. + - MEDIUM: truth-table evidence lacks concrete route-continuity identities and clause derivations. + - LOW: state/checkpoint/PR evidence and the v0.11.2 present-tense sentence need correction. +- Report: `planning/adr-0016-adversarial-ef646b9.md` Craft Review: @@ -149,7 +156,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No owner decision is pending until re-review completes. Jim's choice does not authorize merge or ADR acceptance. +Approve or decline remediation of the route-continuity and ADR-0011 findings. Jim's prior choice does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -161,8 +168,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Push the verification record, confirm exact-head CI, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Add concrete complete-route continuity, precisely supersede ADR-0011's unconditional SDK-primary clause, scope the historical v0.11.2 sentence, and commit a concrete truth table. Then rerun code review, goal verification, exact-head CI, and adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -The first adversarial findings were remediated; adversarial re-review at `dfd14da` found one decision ambiguity. Jim chose journey-local qualification, amendment `fb00f10` implements it, code review passed at `b1e4846`, and 10/10 goal verification passed at `39e2cdf`. Adversarial re-review, Craft, and clean-context remain. No implementation is authorized. +Jim chose journey-local qualification, amendment `fb00f10` implemented it, code review passed at `b1e4846`, and goal verification passed at `39e2cdf`. Adversarial re-review at `ef646b9` found two remaining HIGH blockers. Craft and clean-context have not run. No implementation is authorized.