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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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/50] 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. From afdaa07ec909475f69fff16229952559b1e415ee Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 16:59:21 +0100 Subject: [PATCH 27/50] docs(adr): describe obtainable release truth - Replace detailed policy mechanics with the approved durable release baseline - Keep implementation and developer-skill architecture out of the proposal --- ...eleased-truth-for-public-developer-docs.md | 225 +++--------------- 1 file changed, 33 insertions(+), 192 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 e068d87..b5d856a 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -1,237 +1,78 @@ -# ADR-0016: Released truth for public developer documentation +# ADR-0016: Public documentation describes obtainable releases - **Status:** Proposed -- **Acceptance:** Prospective — pending review and explicit acceptance by Jim Collinson as decision owner. +- **Acceptance:** Prospective; pending human review and acceptance by Jim Collinson - **Date:** 2026-08-12 - **Decision owners:** Jim Collinson - **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) +- **Supersedes:** ADR-0003 (public source-selection default only); ADR-0004 and ADR-0006 (default-branch-driven public provenance advancement only) - **Superseded by:** none -- **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) +- **Related:** `planning/released-antd-v0.11.2-audit.md`; PR #98; follow-up specification and planning documents ## 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. +Public developer documentation is a promise about software developers can obtain and use. -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. +Code on a default branch may not have been released, may not be available through a supported installation route, and may be reverted before release. Documentation based on that code can describe a product that does not exist for the public. -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. +A stable release is the stake in the ground against which public documentation is written and verified. ## Decision Drivers -- Developers must be able to obtain 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. +- Developers must be able to obtain the software the documentation describes. +- Public claims must have stable, auditable provenance. +- Known release defects and limitations must be represented honestly. ## Considered Options -1. **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. -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. +1. Document the latest merged source. +2. Document stable, publicly obtainable releases. Chosen. ## Decision -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 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 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. - -### 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. 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. - -### 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. - -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. - -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. - -Artifact-wide and journey-local failures have different effects: - -- 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. - -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 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. -- **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 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. - -### Journey truth and skill parity - -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 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. -- 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 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 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. +Public developer documentation will describe only stable or general-availability software that the public can obtain through supported distribution or installation routes. -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 documentation will use an explicit release baseline. Where the product spans multiple components, that baseline will identify a coherent set of compatible released components, their exact shipped dependencies, and the compatible deployed Autonomi Network state where relevant. -The existing verification-block invariants remain: +Every technical claim must be supported by the baseline release, its exact shipped dependencies, or verified behavior against the compatible deployed network. -- 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. +A documentation baseline advances only through reviewed promotion of a new public release. Code that has not been released may inform preparation for future documentation, but it cannot support claims in the default public documentation. -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. +Known defects are part of released truth. Affected capabilities must be described with their limitations and safe alternatives, or must not be presented as working. -### Supersession scope and preserved invariants +If no released software supports a claim or developer task, the documentation must state that limitation rather than infer support from unreleased source. -This ADR supersedes only the named default-public source and provenance-advance semantics in Accepted ADRs: +Pre-release documentation, if published, must be clearly separated from the default public documentation. -- **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. +This decision governs public documentation in this repository. It does not decide where a separate developer skill lives or how that skill is assembled. -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. +Implementation details and sequencing belong in a reviewed specification and planning documents. ## 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. -- 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. +- Public documentation corresponds to software developers can obtain. +- Releases provide stable and reproducible verification boundaries. +- Defects cannot be hidden by newer unreleased source. ### 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 promotion or incumbent requalification is neglected, public docs can become stale even while source-movement detection is working. -- 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. +- Documentation may intentionally lag merged development. +- Promoting a release baseline requires verification work. ### 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 deferred mechanics and inventories named above require a separate reviewed specification and execution plan. +- Default branches remain useful for preparing future documentation. ## Validation -This decision is satisfied when all of the following remain true: - -- 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. -- 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. -- 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 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, 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 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, complete routes, global results, selection outcome, and explicit regressions. - -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. +- Every public technical claim resolves to exact released provenance. +- Documented installation routes resolve to the intended public artifacts. +- Unreleased source cannot advance the public documentation baseline. +- Known broken or unverified capabilities are not presented as working. +- Every baseline change leaves a reviewed release-promotion record. ## Notes for AI-assisted work -AI tools helped draft this ADR. 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. +AI may draft but not accept this ADR. Human acceptance is required. Changes to an Accepted decision require a superseding ADR. From f326e0c3f65de0646495da02d6eb74b70dac966f Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:03:26 +0100 Subject: [PATCH 28/50] docs(adr): tighten released-truth decision --- ...eleased-truth-for-public-developer-docs.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 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 b5d856a..54b0bca 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -1,19 +1,19 @@ # ADR-0016: Public documentation describes obtainable releases - **Status:** Proposed -- **Acceptance:** Prospective; pending human review and acceptance by Jim Collinson +- **Acceptance:** Prospective; pending Jim Collinson's human review and acceptance - **Date:** 2026-08-12 - **Decision owners:** Jim Collinson - **Reviewers:** Jim Collinson -- **Supersedes:** ADR-0003 (public source-selection default only); ADR-0004 and ADR-0006 (default-branch-driven public provenance advancement only) +- **Supersedes:** ADR-0003 (public source selection only); ADR-0004 and ADR-0006 (public provenance advancement only) - **Superseded by:** none -- **Related:** `planning/released-antd-v0.11.2-audit.md`; PR #98; follow-up specification and planning documents +- **Related:** `planning/released-antd-v0.11.2-audit.md`; PR #98 ## Context Public developer documentation is a promise about software developers can obtain and use. -Code on a default branch may not have been released, may not be available through a supported installation route, and may be reverted before release. Documentation based on that code can describe a product that does not exist for the public. +Default-branch code may be unreleased, unavailable through supported installation routes, or reverted. Documentation based on it can describe a product the public cannot obtain. A stable release is the stake in the ground against which public documentation is written and verified. @@ -30,21 +30,21 @@ A stable release is the stake in the ground against which public documentation i ## Decision -Public developer documentation will describe only stable or general-availability software that the public can obtain through supported distribution or installation routes. +Public developer documentation will describe only stable or general-availability software available through supported public distribution or installation routes. -The documentation will use an explicit release baseline. Where the product spans multiple components, that baseline will identify a coherent set of compatible released components, their exact shipped dependencies, and the compatible deployed Autonomi Network state where relevant. +The documentation will use an explicit release baseline. For a multi-component product, it identifies compatible released components, exact shipped dependencies, and the compatible deployed Autonomi Network state where relevant. Every technical claim must be supported by the baseline release, its exact shipped dependencies, or verified behavior against the compatible deployed network. -A documentation baseline advances only through reviewed promotion of a new public release. Code that has not been released may inform preparation for future documentation, but it cannot support claims in the default public documentation. +A documentation baseline advances only through reviewed promotion of a public release. Unreleased code may inform future documentation but cannot support default public claims. Known defects are part of released truth. Affected capabilities must be described with their limitations and safe alternatives, or must not be presented as working. -If no released software supports a claim or developer task, the documentation must state that limitation rather than infer support from unreleased source. +If no released software supports a claim or task, the documentation must state that limitation rather than infer support from source. Pre-release documentation, if published, must be clearly separated from the default public documentation. -This decision governs public documentation in this repository. It does not decide where a separate developer skill lives or how that skill is assembled. +This decision governs public documentation in this repository. It does not govern a separate developer skill. Implementation details and sequencing belong in a reviewed specification and planning documents. @@ -52,7 +52,7 @@ Implementation details and sequencing belong in a reviewed specification and pla ### Positive -- Public documentation corresponds to software developers can obtain. +- Public documentation corresponds to obtainable software. - Releases provide stable and reproducible verification boundaries. - Defects cannot be hidden by newer unreleased source. @@ -75,4 +75,4 @@ Implementation details and sequencing belong in a reviewed specification and pla ## Notes for AI-assisted work -AI may draft but not accept this ADR. Human acceptance is required. Changes to an Accepted decision require a superseding ADR. +AI may draft but not accept this ADR. Acceptance requires human review. Later decision changes require a superseding ADR. From 752099ac110182655ec114a724eb236c66d4427e Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:05:20 +0100 Subject: [PATCH 29/50] docs(gsd): record concise ADR scope reset --- planning/STATE.md | 15 +++++++++------ planning/gsd-adr-0016-checkpoint.md | 20 ++++++++++++-------- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 868537e..8e15e99 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: remediate complete-route continuity and ADR-0011 supersession -- Status: adversarial NOT-READY; attended checkpoint +- Task: review concise ADR-0016 redraft +- Status: approved 477-word redraft committed; exact-head 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`; journey-local amendment `fb00f10b5620ce502345fdbdb1689ac7c0014d98` +- Current draft-PR base: `origin/main` at `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; 477-word tightening `f326e0cde7f4dcdf1f687405556f49fd78227875` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -67,9 +67,12 @@ - MEDIUM: branch-local truth-table evidence must include concrete binding, transport, installation, runtime/configuration, and carried-state identities. - LOW: state/checkpoint/PR evidence was stale, and the historical v0.11.2 defect sentence needs past-tense scoping. - Craft and clean-context did not run because adversarial blocked advancement. +- Jim then directed a scope reset: ADR-0016 should state only the durable rule that public documentation covers stable software the public can obtain. Skill ownership, journey models, route truth tables, comparison algorithms, and implementation mechanics moved out of the ADR. +- Concise content commit `afdaa07` replaced the detailed proposal; `f326e0c` tightened it to 477 words including metadata and headings. It now supersedes only the public source-selection/provenance clauses in ADR-0003, ADR-0004, and ADR-0006 and explicitly leaves any separate developer skill out of scope. +- Exact-head ADR Governance, 20 local governance tests, diff check, and draft-PR CI passed for `f326e0c`. The earlier route-continuity and ADR-0011 findings applied to removed decisions and require fresh review rather than mechanical remediation. - Clean-context gate: deferred because the Claude lane was unavailable due to expired OAuth. No substitute was used. - `models: unavailable (auth) · 0s` -- CI arbiter: draft PR #98. Exact reviewed head `ef646b9` passed ADR Governance and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. +- CI arbiter: draft PR #98. Exact concise head `f326e0c` passed ADR Governance run `33188143434` 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 @@ -81,4 +84,4 @@ ## Next -- With Jim's attended approval, add concrete complete-route continuity, precisely supersede ADR-0011's unconditional SDK-primary clause, scope the historical v0.11.2 sentence, and add inspectable concrete truth-table evidence; then rerun code review, verification, CI, and adversarial. Do not merge, accept the ADR, or begin implementation. +- Run fresh code review and goal verification against concise ADR head `f326e0c`, persist exact-SHA evidence, 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 c5c5f87..7857542 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -8,15 +8,17 @@ Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and cle ## Status -Revise — journey-local code review and goal verification passed, but adversarial re-review found route-continuity and ADR-0011 blockers. +Continue — Jim approved a concise target-architecture redraft; the 477-word ADR and exact-head CI are green, with fresh 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 review -Unreviewed backlog if deferred: Craft and clean-context remain unrun because adversarial did not pass +Review cadence: per-unit fresh review after scope reset +Unreviewed backlog if deferred: Craft and clean-context remain unrun until the concise ADR passes adversarial review ## 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. 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. +Jim approved a scope reset for Proposed ADR-0016. The ADR now states one durable target invariant: public documentation describes stable software the public can obtain, using an explicit released baseline with exact provenance. Unreleased source may prepare future documentation but cannot support default public claims. Known defects must be represented honestly. + +Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside this ADR. The proposal now partially supersedes only ADR-0003, ADR-0004, and ADR-0006. A separate developer skill is explicitly out of scope. 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. @@ -27,7 +29,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 `ef646b9` 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 concise head `f326e0c` passed ADR Governance run `33188143434` and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. Local fast gate / `.gsd/gate.sh`: @@ -77,6 +79,7 @@ Results: - 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`. +- Concise redraft `afdaa07` replaced the detailed decision; tightening commit `f326e0c` reduced the complete ADR to 477 words. ADR governance, 20 tests, diff check, and exact-head CI passed. ## Honesty rules check @@ -140,6 +143,7 @@ Adversarial review: - 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` +- Scope-reset disposition: the journey, route, skill, and ADR-0011 decisions reviewed at `ef646b9` were removed from ADR-0016. Fresh review of the concise target decision is pending. Craft Review: @@ -156,7 +160,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 route-continuity and ADR-0011 findings. Jim's prior choice does not authorize merge or ADR acceptance. +No owner decision is pending until the concise ADR completes fresh review. The redraft does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -168,8 +172,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -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. +Run fresh code review and goal verification against `f326e0c`, persist exact-SHA reports, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -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. +Jim replaced the detailed journey-local proposal with a 477-word target-architecture decision at `f326e0c`. Exact-head CI is green, but all substantive reviews predate the scope reset. Fresh code review, verification, adversarial, Craft, and clean-context remain. No implementation is authorized. From 85fde835e16d1891162c86abfed373e5bc36ec2a Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:11:11 +0100 Subject: [PATCH 30/50] docs(gsd): record concise ADR code review --- planning/STATE.md | 7 +++--- planning/adr-0016-code-review-752099a.md | 30 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 8 ++++--- 3 files changed, 39 insertions(+), 6 deletions(-) create mode 100644 planning/adr-0016-code-review-752099a.md diff --git a/planning/STATE.md b/planning/STATE.md index 8e15e99..74d88e0 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: review concise ADR-0016 redraft -- Status: approved 477-word redraft committed; exact-head CI green; code review pending +- Task: verify concise ADR-0016 redraft +- Status: concise 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 @@ -70,6 +70,7 @@ - Jim then directed a scope reset: ADR-0016 should state only the durable rule that public documentation covers stable software the public can obtain. Skill ownership, journey models, route truth tables, comparison algorithms, and implementation mechanics moved out of the ADR. - Concise content commit `afdaa07` replaced the detailed proposal; `f326e0c` tightened it to 477 words including metadata and headings. It now supersedes only the public source-selection/provenance clauses in ADR-0003, ADR-0004, and ADR-0006 and explicitly leaves any separate developer skill out of scope. - Exact-head ADR Governance, 20 local governance tests, diff check, and draft-PR CI passed for `f326e0c`. The earlier route-continuity and ADR-0011 findings applied to removed decisions and require fresh review rather than mechanical remediation. +- Fresh code review at `752099a`: passed with no findings. The 477-word ADR, template, American English, partial supersession, target-architecture scope, Accepted-ADR immutability, and exact-head CI all passed. Report: `planning/adr-0016-code-review-752099a.md`. - 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 concise head `f326e0c` passed ADR Governance run `33188143434` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -84,4 +85,4 @@ ## Next -- Run fresh code review and goal verification against concise ADR head `f326e0c`, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Run fresh goal verification against the concise ADR, persist exact-SHA evidence, 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-752099a.md b/planning/adr-0016-code-review-752099a.md new file mode 100644 index 0000000..2e48711 --- /dev/null +++ b/planning/adr-0016-code-review-752099a.md @@ -0,0 +1,30 @@ +# ADR-0016 code review — 752099a + +- Date: 2026-08-28 +- Reviewed commit: `752099ac110182655ec114a724eb236c66d4427e` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `passed` +- Word count: 477, including title, metadata, and headings + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Diff check against the current PR base: passed. +- Accepted ADRs: unchanged. +- Template, American English, scope, and partial supersession: passed. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful branch-scope no-ops. +- Worktree: clean at review time. + +## Findings + +None. + +## Remaining risks + +- ADR-0016 remains Proposed and requires human acceptance. +- Implementation requires a reviewed specification, planning documents, and a fresh release audit. +- Goal verification, adversarial, Craft, and clean-context remain pending. +- Same-model review provides weaker independence than cross-model review. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 7857542..1b92cb1 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 approved a concise target-architecture redraft; the 477-word ADR and exact-head CI are green, with fresh review pending. +Continue — the 477-word concise ADR passed fresh code review; 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 fresh review after scope reset @@ -51,6 +51,7 @@ Files changed/artifacts produced: - `planning/adr-0016-code-review-b1e4846.md` - `planning/adr-0016-verification-39e2cdf.md` - `planning/adr-0016-adversarial-ef646b9.md` +- `planning/adr-0016-code-review-752099a.md` Checks run: @@ -80,6 +81,7 @@ Results: - 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`. - Concise redraft `afdaa07` replaced the detailed decision; tightening commit `f326e0c` reduced the complete ADR to 477 words. ADR governance, 20 tests, diff check, and exact-head CI passed. +- Fresh concise-ADR code review at `752099a`: passed with no findings. Report: `planning/adr-0016-code-review-752099a.md`. ## Honesty rules check @@ -172,8 +174,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run fresh code review and goal verification against `f326e0c`, persist exact-SHA reports, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Run fresh goal verification against the concise ADR, persist the exact-SHA report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -Jim replaced the detailed journey-local proposal with a 477-word target-architecture decision at `f326e0c`. Exact-head CI is green, but all substantive reviews predate the scope reset. Fresh code review, verification, adversarial, Craft, and clean-context remain. No implementation is authorized. +Jim replaced the detailed journey-local proposal with a 477-word target-architecture decision at `f326e0c`. Exact-head CI and fresh code review are green. Goal verification, adversarial, Craft, and clean-context remain. No implementation is authorized. From d09520e6f766a7ca51f0d735165aebd0410f229e Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:16:50 +0100 Subject: [PATCH 31/50] docs(gsd): reconcile concise ADR verification --- planning/STATE.md | 14 ++++++--- planning/adr-0016-verification-85fde83.md | 37 +++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 10 +++--- 3 files changed, 52 insertions(+), 9 deletions(-) create mode 100644 planning/adr-0016-verification-85fde83.md diff --git a/planning/STATE.md b/planning/STATE.md index 74d88e0..a044b92 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -16,10 +16,11 @@ ## 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. +- Public documentation describes stable or general-availability software available through supported public routes. +- An explicit release baseline provides exact provenance for released components, shipped dependencies, and relevant deployed-network behavior. +- Unreleased source may prepare future documentation but cannot support default public claims. +- Known defects and unsupported tasks are represented honestly; pre-release documentation remains separate. +- A separate developer skill is outside this decision. ## Review State @@ -71,6 +72,9 @@ - Concise content commit `afdaa07` replaced the detailed proposal; `f326e0c` tightened it to 477 words including metadata and headings. It now supersedes only the public source-selection/provenance clauses in ADR-0003, ADR-0004, and ADR-0006 and explicitly leaves any separate developer skill out of scope. - Exact-head ADR Governance, 20 local governance tests, diff check, and draft-PR CI passed for `f326e0c`. The earlier route-continuity and ADR-0011 findings applied to removed decisions and require fresh review rather than mechanical remediation. - Fresh code review at `752099a`: passed with no findings. The 477-word ADR, template, American English, partial supersession, target-architecture scope, Accepted-ADR immutability, and exact-head CI all passed. Report: `planning/adr-0016-code-review-752099a.md`. +- Goal verification at `85fde83`: ADR content passed all 11 applicable decision goals; the twelfth state/PR accuracy goal found two bookkeeping gaps. Report: `planning/adr-0016-verification-85fde83.md`. + - `STATE.md` still described removed skill/mode intent. + - PR #98 still called the completed fresh code review pending. - 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 concise head `f326e0c` passed ADR Governance run `33188143434` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -85,4 +89,4 @@ ## Next -- Run fresh goal verification against the concise ADR, persist exact-SHA evidence, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Correct the state and PR-body drift, rerun exact-head goal verification, and then 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-85fde83.md b/planning/adr-0016-verification-85fde83.md new file mode 100644 index 0000000..fb9cb31 --- /dev/null +++ b/planning/adr-0016-verification-85fde83.md @@ -0,0 +1,37 @@ +# ADR-0016 goal verification — 85fde83 + +- Date: 2026-08-28 +- Reviewed commit: `85fde835e16d1891162c86abfed373e5bc36ec2a` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `gaps_found` +- Score: 11/12 goals verified + +## Verified + +The concise ADR passed all decision-content goals: obtainable stable releases, explicit baseline, coherent multi-component provenance, reviewed promotion, honest defects, separated previews, skill exclusion, deferred implementation, precise partial supersession, Proposed status, template conformance, and the 477-word cap. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Word count: 477 including metadata and headings. +- Diff check: passed. +- Accepted ADRs: byte-identical to the current base. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. +- Worktree and remote head: clean and aligned at review time. + +## Gaps + +- `planning/STATE.md` still described skill inclusion and detailed verification-mode machinery as current intent despite the later scope reset. +- PR #98 still said fresh code review was pending after it had passed. + +These are state and PR-body accuracy gaps, not ADR-content gaps. + +## Remaining risks + +- ADR-0016 remains Proposed and requires human acceptance. +- Adversarial, Craft, and clean-context remain pending. +- A fresh release audit is required before implementation. +- Same-model verification provides weaker independence. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 1b92cb1..d6007e7 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 — the 477-word concise ADR passed fresh code review; goal verification is pending. +Revise — the concise ADR passed all decision-content checks, but goal verification found stale state and PR wording. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit fresh review after scope reset @@ -52,6 +52,7 @@ Files changed/artifacts produced: - `planning/adr-0016-verification-39e2cdf.md` - `planning/adr-0016-adversarial-ef646b9.md` - `planning/adr-0016-code-review-752099a.md` +- `planning/adr-0016-verification-85fde83.md` Checks run: @@ -82,6 +83,7 @@ Results: - 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`. - Concise redraft `afdaa07` replaced the detailed decision; tightening commit `f326e0c` reduced the complete ADR to 477 words. ADR governance, 20 tests, diff check, and exact-head CI passed. - Fresh concise-ADR code review at `752099a`: passed with no findings. Report: `planning/adr-0016-code-review-752099a.md`. +- Concise-ADR goal verification at `85fde83`: 11/12 goals verified; ADR content passed, while stale state and PR wording failed the evidence-accuracy goal. Report: `planning/adr-0016-verification-85fde83.md`. ## Honesty rules check @@ -162,7 +164,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 concise ADR completes fresh review. The redraft does not authorize merge or ADR acceptance. +No architecture decision is pending. Attended verification requires a checkpoint before rerunning after the bookkeeping correction. The redraft does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -174,8 +176,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run fresh goal verification against the concise ADR, persist the exact-SHA report, and rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Correct the PR body, rerun exact-head goal verification, and then rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -Jim replaced the detailed journey-local proposal with a 477-word target-architecture decision at `f326e0c`. Exact-head CI and fresh code review are green. Goal verification, adversarial, Craft, and clean-context remain. No implementation is authorized. +Jim replaced the detailed proposal with a 477-word target-architecture decision at `f326e0c`. Exact-head CI and code review are green. Goal verification found only state/PR bookkeeping drift; adversarial, Craft, and clean-context remain. No implementation is authorized. From 58545cd04936d1c13c44d27d80acf94cec6cb8e9 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:10:15 +0100 Subject: [PATCH 32/50] docs(gsd): correct concise ADR checkpoint --- planning/STATE.md | 9 ++--- planning/adr-0016-verification-d09520e.md | 42 +++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 20 ++++++----- 3 files changed, 58 insertions(+), 13 deletions(-) create mode 100644 planning/adr-0016-verification-d09520e.md diff --git a/planning/STATE.md b/planning/STATE.md index a044b92..136a3f2 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -5,13 +5,13 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation - Task: verify concise ADR-0016 redraft -- Status: concise code review passed; goal verification pending +- Status: concise ADR content passed; checkpoint bookkeeping corrected; exact-head reverification 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 `49e202c818bab1be780b81c28e5d0718cfb89b1c` -- Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; 477-word tightening `f326e0cde7f4dcdf1f687405556f49fd78227875` +- Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; 477-word tightening `f326e0c3f65de0646495da02d6eb74b70dac966f` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -75,9 +75,10 @@ - Goal verification at `85fde83`: ADR content passed all 11 applicable decision goals; the twelfth state/PR accuracy goal found two bookkeeping gaps. Report: `planning/adr-0016-verification-85fde83.md`. - `STATE.md` still described removed skill/mode intent. - PR #98 still called the completed fresh code review pending. +- Reverification at `d09520e`: ADR content and the first bookkeeping corrections passed; two further checkpoint accuracy gaps and the invalid recorded `f326e0c` full SHA remained. These are corrected in the current state/checkpoint update. - 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 concise head `f326e0c` passed ADR Governance run `33188143434` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. +- CI arbiter: draft PR #98. Exact reverification head `d09520e` passed ADR Governance run `33189218449` 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 @@ -89,4 +90,4 @@ ## Next -- Correct the state and PR-body drift, rerun exact-head goal verification, and then rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Rerun exact-head goal verification after the final checkpoint corrections, then 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-d09520e.md b/planning/adr-0016-verification-d09520e.md new file mode 100644 index 0000000..32f78da --- /dev/null +++ b/planning/adr-0016-verification-d09520e.md @@ -0,0 +1,42 @@ +# ADR-0016 goal verification — d09520e + +- Date: 2026-08-28 +- Reviewed commit: `d09520e6f766a7ca51f0d735165aebd0410f229e` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `gaps_found` +- Score: 11/12 goals verified + +## Verified + +- All concise ADR-content goals passed. +- State Decision Intent matched the scope reset. +- PR #98 accurately reported the concise decision, 477-word count, completed code review, historical audit, scope-gated checks, and pending gates. +- Removed journey, skill-architecture, route, and comparison decisions were not presented as current ADR content. +- Accepted ADRs remained byte-identical to the current base. +- Exact-head ADR Governance and GitBook checks passed. + +## Gaps + +- `planning/STATE.md` recorded an invalid full SHA for tightening commit `f326e0c`. +- The checkpoint called an older review the latest passing review, retained a completed PR-body correction as its next step, and did not record the exact `d09520e` CI run. + +These were bookkeeping/evidence-accuracy gaps, not ADR-content defects. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Word count: 477. +- Diff check: passed. +- Worktree and remote head: clean and aligned at review time. +- Exact-head ADR Governance run `33189218449`, job `98910092392`: passed. +- Both GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. + +## Remaining risks + +- ADR-0016 remains Proposed and requires human acceptance. +- Adversarial, Craft, and clean-context remain pending. +- A fresh release audit is required before implementation. +- Same-model verification provides weaker independence. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index d6007e7..a395a4d 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 -Revise — the concise ADR passed all decision-content checks, but goal verification found stale state and PR wording. +Revise — the concise ADR passed all decision-content checks; final checkpoint bookkeeping is corrected and reverification remains. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit fresh review after scope reset @@ -29,7 +29,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 concise head `f326e0c` passed ADR Governance run `33188143434` and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. +- Status: draft PR #98 is open. Exact reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. Local fast gate / `.gsd/gate.sh`: @@ -53,6 +53,7 @@ Files changed/artifacts produced: - `planning/adr-0016-adversarial-ef646b9.md` - `planning/adr-0016-code-review-752099a.md` - `planning/adr-0016-verification-85fde83.md` +- `planning/adr-0016-verification-d09520e.md` Checks run: @@ -84,6 +85,7 @@ Results: - Concise redraft `afdaa07` replaced the detailed decision; tightening commit `f326e0c` reduced the complete ADR to 477 words. ADR governance, 20 tests, diff check, and exact-head CI passed. - Fresh concise-ADR code review at `752099a`: passed with no findings. Report: `planning/adr-0016-code-review-752099a.md`. - Concise-ADR goal verification at `85fde83`: 11/12 goals verified; ADR content passed, while stale state and PR wording failed the evidence-accuracy goal. Report: `planning/adr-0016-verification-85fde83.md`. +- Reverification at `d09520e`: ADR content and earlier corrections passed; it found only the invalid recorded full `f326e0c` SHA and stale checkpoint review/next-step/CI wording. Those are corrected in this update. ## Honesty rules check @@ -93,7 +95,7 @@ Results: - 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, 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. +- Local vs CI consistency: no conflict observed; exact reverification head `d09520e` was green. ## Ledger / forks @@ -104,8 +106,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: latest passing review `481ca8cb653b32823851d38b2bcc36b4007ddf7a`; prior issue rounds `e3df509` and `2dd687b` -- Result: Passed after two recorded remediation rounds +- Reviewed commit: latest concise-ADR review `752099ac110182655ec114a724eb236c66d4427e` +- Result: Passed with no findings after the scope reset - 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. @@ -114,7 +116,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. -- Reports: `planning/adr-0016-code-review-e3df509.md`, `planning/adr-0016-code-review-2dd687b.md`, and `planning/adr-0016-code-review-481ca8c.md` +- Current report: `planning/adr-0016-code-review-752099a.md`; earlier reports are historical pre-reset evidence Clean-context test: @@ -164,7 +166,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No architecture decision is pending. Attended verification requires a checkpoint before rerunning after the bookkeeping correction. The redraft does not authorize merge or ADR acceptance. +No architecture decision is pending. Attended verification requires reverification after this final bookkeeping correction. The redraft does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -176,8 +178,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Correct the PR body, rerun exact-head goal verification, and then rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Rerun exact-head goal verification, then adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -Jim replaced the detailed proposal with a 477-word target-architecture decision at `f326e0c`. Exact-head CI and code review are green. Goal verification found only state/PR bookkeeping drift; adversarial, Craft, and clean-context remain. No implementation is authorized. +Jim replaced the detailed proposal with a 477-word target-architecture decision at `f326e0c`. ADR content, exact-head CI, and code review are green. Goal reverification found only bookkeeping drift, now corrected; adversarial, Craft, and clean-context remain. No implementation is authorized. From d18a63b62f3e7cfdc1e2d72863fa14fc2b60de82 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:18:53 +0100 Subject: [PATCH 33/50] docs(gsd): record final concise ADR verification --- planning/STATE.md | 7 ++-- planning/adr-0016-verification-58545cd.md | 42 +++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 10 +++--- 3 files changed, 52 insertions(+), 7 deletions(-) create mode 100644 planning/adr-0016-verification-58545cd.md diff --git a/planning/STATE.md b/planning/STATE.md index 136a3f2..90cfe34 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 concise ADR-0016 redraft -- Status: concise ADR content passed; checkpoint bookkeeping corrected; exact-head reverification pending +- Task: adversarial review of concise ADR-0016 +- Status: concise code review and 12/12 goal verification passed; adversarial pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -76,6 +76,7 @@ - `STATE.md` still described removed skill/mode intent. - PR #98 still called the completed fresh code review pending. - Reverification at `d09520e`: ADR content and the first bookkeeping corrections passed; two further checkpoint accuracy gaps and the invalid recorded `f326e0c` full SHA remained. These are corrected in the current state/checkpoint update. +- Final exact-head reverification at `58545cd`: passed 12/12 with no gaps. Report: `planning/adr-0016-verification-58545cd.md`. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -90,4 +91,4 @@ ## Next -- Rerun exact-head goal verification after the final checkpoint corrections, then rerun adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Run fresh adversarial review against the concise ADR and branch-local evidence. 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-58545cd.md b/planning/adr-0016-verification-58545cd.md new file mode 100644 index 0000000..a9975b1 --- /dev/null +++ b/planning/adr-0016-verification-58545cd.md @@ -0,0 +1,42 @@ +# ADR-0016 goal verification — 58545cd + +- Date: 2026-08-28 +- Reviewed commit: `58545cd04936d1c13c44d27d80acf94cec6cb8e9` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: verifier — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `passed` +- Score: 12/12 goals verified + +## Verified + +- All concise ADR decision goals passed. +- ADR-0016 remained unchanged from tightening commit `f326e0c3f65de0646495da02d6eb74b70dac966f` and contained 477 words including metadata and headings. +- All prior bookkeeping gaps were corrected. +- State, checkpoint, ADR, and PR body agreed on the concise scope. +- No current skill, journey, route, or comparison architecture remained. +- Partial supersession of ADR-0003, ADR-0004, and ADR-0006 was limited appropriately. +- All Accepted ADRs were byte-identical to the current base. +- ADR-0016 remained Proposed; no implementation or rendered-doc change was included. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Diff check: passed. +- Worktree and remote head: clean and aligned at review time. +- PR #98: open, draft, exact head, and mergeable. +- Exact-head ADR Governance run `33202671819`, job `98955766230`: passed. +- Both GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. + +## Gaps + +None. + +## Remaining risks + +- Adversarial, Craft, and clean-context remain pending. +- ADR acceptance requires Jim's human decision. +- A fresh release audit is required before implementation. +- Same-model verification provides weaker independence. +- The branch is behind current base; any content-changing integration requires renewed review. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index a395a4d..48d7c41 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 -Revise — the concise ADR passed all decision-content checks; final checkpoint bookkeeping is corrected and reverification remains. +Continue — concise ADR code review and final 12/12 goal reverification passed; adversarial 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 fresh review after scope reset @@ -54,6 +54,7 @@ Files changed/artifacts produced: - `planning/adr-0016-code-review-752099a.md` - `planning/adr-0016-verification-85fde83.md` - `planning/adr-0016-verification-d09520e.md` +- `planning/adr-0016-verification-58545cd.md` Checks run: @@ -86,6 +87,7 @@ Results: - Fresh concise-ADR code review at `752099a`: passed with no findings. Report: `planning/adr-0016-code-review-752099a.md`. - Concise-ADR goal verification at `85fde83`: 11/12 goals verified; ADR content passed, while stale state and PR wording failed the evidence-accuracy goal. Report: `planning/adr-0016-verification-85fde83.md`. - Reverification at `d09520e`: ADR content and earlier corrections passed; it found only the invalid recorded full `f326e0c` SHA and stale checkpoint review/next-step/CI wording. Those are corrected in this update. +- Final reverification at `58545cd`: passed 12/12 with no gaps. Report: `planning/adr-0016-verification-58545cd.md`. ## Honesty rules check @@ -166,7 +168,7 @@ The v0.11.2 audit is historical evidence. `antd` v0.12.0 has since released and ## Open questions / decisions for Jim -No architecture decision is pending. Attended verification requires reverification after this final bookkeeping correction. The redraft does not authorize merge or ADR acceptance. +No owner decision is pending until the gauntlet completes. The redraft does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -178,8 +180,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Rerun exact-head goal verification, then adversarial. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Run fresh adversarial review against the concise ADR and branch-local evidence. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -Jim replaced the detailed proposal with a 477-word target-architecture decision at `f326e0c`. ADR content, exact-head CI, and code review are green. Goal reverification found only bookkeeping drift, now corrected; adversarial, Craft, and clean-context remain. No implementation is authorized. +Jim replaced the detailed proposal with a 477-word target-architecture decision at `f326e0c`. Code review, exact-head CI, and final 12/12 goal verification are green. Adversarial, Craft, and clean-context remain. No implementation is authorized. From dfe21614f5de6cb008f6a4c58c85bd8757ce7560 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:28:22 +0100 Subject: [PATCH 34/50] docs(adr): align release evidence validation --- adr/ADR-0016-released-truth-for-public-developer-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 54b0bca..038f09c 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -67,7 +67,7 @@ Implementation details and sequencing belong in a reviewed specification and pla ## Validation -- Every public technical claim resolves to exact released provenance. +- Every public technical claim resolves to exact release, shipped-dependency, or verified deployed-network evidence. - Documented installation routes resolve to the intended public artifacts. - Unreleased source cannot advance the public documentation baseline. - Known broken or unverified capabilities are not presented as working. From fc49173dc040425429a4cc298eb3811a23650b5a Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:29:07 +0100 Subject: [PATCH 35/50] docs(gsd): record concise ADR adversarial pass --- planning/STATE.md | 11 +++++--- planning/adr-0016-adversarial-d18a63b.md | 36 ++++++++++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 10 ++++--- 3 files changed, 49 insertions(+), 8 deletions(-) create mode 100644 planning/adr-0016-adversarial-d18a63b.md diff --git a/planning/STATE.md b/planning/STATE.md index 90cfe34..aa9b5db 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: adversarial review of concise ADR-0016 -- Status: concise code review and 12/12 goal verification passed; adversarial pending +- Task: revalidate concise ADR-0016 after adversarial nit +- Status: adversarial passed READY-WITH-NITS; evidence wording corrected; exact-head revalidation 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 `49e202c818bab1be780b81c28e5d0718cfb89b1c` -- Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; 477-word tightening `f326e0c3f65de0646495da02d6eb74b70dac966f` +- Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; tightening `f326e0c3f65de0646495da02d6eb74b70dac966f`; evidence-alignment correction `dfe2161` - Implementation: not started; ADR acceptance remains human-only ## Decision Intent @@ -77,6 +77,9 @@ - PR #98 still called the completed fresh code review pending. - Reverification at `d09520e`: ADR content and the first bookkeeping corrections passed; two further checkpoint accuracy gaps and the invalid recorded `f326e0c` full SHA remained. These are corrected in the current state/checkpoint update. - Final exact-head reverification at `58545cd`: passed 12/12 with no gaps. Report: `planning/adr-0016-verification-58545cd.md`. +- Fresh adversarial review at `d18a63b`: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. Report: `planning/adr-0016-adversarial-d18a63b.md`. + - LOW: validation wording should preserve the deployed-network evidence path. Corrected in `dfe2161`. + - LOW: PR body lagged final verification. Corrected after review. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -91,4 +94,4 @@ ## Next -- Run fresh adversarial review against the concise ADR and branch-local evidence. Craft and clean-context follow only after adversarial passes. Do not merge, accept the ADR, or begin implementation. +- Revalidate exact head after the one-line evidence correction, then run Craft and clean-context. Do not merge, accept the ADR, or begin implementation. diff --git a/planning/adr-0016-adversarial-d18a63b.md b/planning/adr-0016-adversarial-d18a63b.md new file mode 100644 index 0000000..2bdedff --- /dev/null +++ b/planning/adr-0016-adversarial-d18a63b.md @@ -0,0 +1,36 @@ +# ADR-0016 adversarial review — d18a63b + +- Date: 2026-08-28 +- Reviewed commit: `d18a63b62f3e7cfdc1e2d72863fa14fc2b60de82` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `READY-WITH-NITS` + +## Findings + +No CRITICAL, HIGH, or MEDIUM findings. + +### LOW — Validation narrowed the deployed-network evidence path + +The decision allowed release, shipped-dependency, or verified deployed-network evidence, while one validation bullet referred only to released provenance. This was non-blocking because the decision remained clear. It was corrected in follow-up content commit `dfe2161`. + +### LOW — PR body lagged final verification + +The PR body still called completed reverification pending. This understated readiness rather than engineering a false green and was corrected after review. + +## Durable-decision result + +The concise decision survived attacks on obtainable releases, coherent provenance, reviewed promotion, unreleased-source exclusion, honest defects, preview separation, skill exclusion, implementation deferral, and partial supersession. + +## Evidence integrity + +- Exact local/remote head and clean worktree confirmed. +- ADR remained 477 words at review time and unchanged from the tightening content commit. +- ADR governance, 20 tests, diff check, exact-head CI, and GitBook checks passed. +- Accepted ADRs were byte-identical to the current base. +- Prose/sweep checks were scope-gate no-ops. +- Craft and clean-context had not yet run. + +## Independence + +This used the same model/provider as other concise-review lanes. No second provider was available, so independence evidence is weaker. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 48d7c41..9a1a931 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 — concise ADR code review and final 12/12 goal reverification passed; adversarial review is pending. +Continue — adversarial review passed READY-WITH-NITS; one evidence-wording nit is corrected and exact-head revalidation is pending. Meaningful work-unit? Yes — this proposal changes the repository's durable public source-of-truth and drift semantics. Review cadence: per-unit fresh review after scope reset @@ -55,6 +55,7 @@ Files changed/artifacts produced: - `planning/adr-0016-verification-85fde83.md` - `planning/adr-0016-verification-d09520e.md` - `planning/adr-0016-verification-58545cd.md` +- `planning/adr-0016-adversarial-d18a63b.md` Checks run: @@ -88,6 +89,7 @@ Results: - Concise-ADR goal verification at `85fde83`: 11/12 goals verified; ADR content passed, while stale state and PR wording failed the evidence-accuracy goal. Report: `planning/adr-0016-verification-85fde83.md`. - Reverification at `d09520e`: ADR content and earlier corrections passed; it found only the invalid recorded full `f326e0c` SHA and stale checkpoint review/next-step/CI wording. Those are corrected in this update. - Final reverification at `58545cd`: passed 12/12 with no gaps. Report: `planning/adr-0016-verification-58545cd.md`. +- Adversarial review at `d18a63b`: READY-WITH-NITS with no blocking findings. Validation wording and stale PR-body nits were corrected. Report: `planning/adr-0016-adversarial-d18a63b.md`. ## Honesty rules check @@ -168,7 +170,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 gauntlet completes. The redraft does not authorize merge or ADR acceptance. +No owner decision is pending until exact-head revalidation, Craft, and clean-context complete. The redraft does not authorize merge or ADR acceptance. PR / upstream action gate, if applicable: @@ -180,8 +182,8 @@ PR / upstream action gate, if applicable: ## Recommended next step -Run fresh adversarial review against the concise ADR and branch-local evidence. Craft and clean-context follow only after adversarial passes. Do not merge, accept ADR-0016, or begin implementation. +Revalidate exact head after the one-line evidence correction, then run Craft and clean-context. Do not merge, accept ADR-0016, or begin implementation. ## Handoff note -Jim replaced the detailed proposal with a 477-word target-architecture decision at `f326e0c`. Code review, exact-head CI, and final 12/12 goal verification are green. Adversarial, Craft, and clean-context remain. No implementation is authorized. +Jim replaced the detailed proposal with a concise target-architecture decision. Code review, CI, goal verification, and adversarial review are green. One adversarial wording nit was corrected in `dfe2161`; exact-head revalidation, Craft, and clean-context remain. No implementation is authorized. From dcf7c8c5ca5199f174b5d493c3a75215933e3f4b Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:34:22 +0100 Subject: [PATCH 36/50] docs(gsd): reconcile concise ADR checkpoint --- planning/STATE.md | 8 +- planning/adr-0016-code-review-fc49173.md | 34 ++++ planning/gsd-adr-0016-checkpoint.md | 214 +++++++---------------- 3 files changed, 106 insertions(+), 150 deletions(-) create mode 100644 planning/adr-0016-code-review-fc49173.md diff --git a/planning/STATE.md b/planning/STATE.md index aa9b5db..1956397 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: revalidate concise ADR-0016 after adversarial nit -- Status: adversarial passed READY-WITH-NITS; evidence wording corrected; exact-head revalidation pending +- Task: reconcile concise ADR checkpoint before final gates +- Status: ADR passed focused review; checkpoint contradiction found; attended checkpoint - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -80,6 +80,8 @@ - Fresh adversarial review at `d18a63b`: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. Report: `planning/adr-0016-adversarial-d18a63b.md`. - LOW: validation wording should preserve the deployed-network evidence path. Corrected in `dfe2161`. - LOW: PR body lagged final verification. Corrected after review. +- Focused code review at `fc49173`: ADR content passed with no findings; one MEDIUM checkpoint-consistency issue remained. Report: `planning/adr-0016-code-review-fc49173.md`. + - The accumulated checkpoint mixed current READY-WITH-NITS status with historical blocker/pending language. It is replaced by a concise current checkpoint; detailed history remains in the review reports. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -94,4 +96,4 @@ ## Next -- Revalidate exact head after the one-line evidence correction, then run Craft and clean-context. Do not merge, accept the ADR, or begin implementation. +- With Jim's attended approval, rerun focused exact-head review of the concise checkpoint, then run Craft and clean-context. Do not merge, accept the ADR, or begin implementation. diff --git a/planning/adr-0016-code-review-fc49173.md b/planning/adr-0016-code-review-fc49173.md new file mode 100644 index 0000000..50e28ae --- /dev/null +++ b/planning/adr-0016-code-review-fc49173.md @@ -0,0 +1,34 @@ +# ADR-0016 code review — fc49173 + +- Date: 2026-08-28 +- Reviewed commit: `fc49173dc040425429a4cc298eb3811a23650b5a` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: codereviewer — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `issues_found` + +## ADR result + +The ADR passed with no findings. Its evidence-validation wording matched the Decision, the document remained durable and template-conformant at 481 words, and its partial supersession remained correct. + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- Diff check: passed. +- Worktree and remote head: clean and aligned at review time. +- Accepted ADRs: unchanged. +- Exact-head ADR Governance and GitBook checks: passed. +- Prose/sweep checks: successful scope-gate no-ops. + +## MEDIUM finding + +The checkpoint's summary recorded adversarial `READY-WITH-NITS`, but its historical detail still said `Blockers` and that adversarial review was pending. It also attributed pending Craft and clean-context to an old blocker rather than listing them as the next gates. + +Required disposition: replace the accumulated checkpoint with a concise current checkpoint and leave detailed history in the committed review reports. + +## Remaining risks + +- Craft and clean-context remain pending. +- Same-model review provides weaker independence. +- ADR acceptance remains human-only. +- A fresh release audit and reviewed specification are required before implementation. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 9a1a931..ee591d7 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -1,189 +1,109 @@ -# GSD Checkpoint — Proposed ADR-0016 review +# GSD Checkpoint — Concise Proposed ADR-0016 -Date: 2026-08-20 +Date: 2026-08-28 Project: Autonomi Developer Documentation -Slice/question: Should released truth replace moving merged truth as the default public documentation source? +Slice/question: Should public documentation describe only stable software the public can obtain? Prepared by: orchestrator -Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and clean-context not run after adversarial blocker +Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and clean-context pending ## Status -Continue — adversarial review passed READY-WITH-NITS; one evidence-wording nit is corrected and exact-head revalidation is pending. +Revise — ADR content passed focused review, but the accumulated checkpoint contradicted the current review status. This file replaces it with the current state; exact-head 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 fresh review after scope reset -Unreviewed backlog if deferred: Craft and clean-context remain unrun until the concise ADR passes adversarial review +Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. +Review cadence: per-unit +Unreviewed backlog: Craft and clean-context ## What happened -Jim approved a scope reset for Proposed ADR-0016. The ADR now states one durable target invariant: public documentation describes stable software the public can obtain, using an explicit released baseline with exact provenance. Unreleased source may prepare future documentation but cannot support default public claims. Known defects must be represented honestly. +Jim replaced the detailed proposal with a concise target decision: public documentation describes stable or general-availability software available through supported public routes. An explicit release baseline provides exact provenance; unreleased source cannot support default public claims; defects and unsupported tasks are represented honestly. -Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside this ADR. The proposal now partially supersedes only ADR-0003, ADR-0004, and ADR-0006. A separate developer skill is explicitly out of scope. +The ADR is 481 words including metadata and headings. Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside its scope. It partially supersedes only ADR-0003, ADR-0004, and ADR-0006. -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. +ADR-0016 remains Proposed. No implementation, rendered docs, skill, CI, test, or Accepted ADR changed. ## Evidence 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as branch-scope no-ops, not substantive coverage. +- Location: draft PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 +- Exact reviewed head: `fc49173dc040425429a4cc298eb3811a23650b5a` +- ADR Governance run `33204071304`, job `98960532646`: passed +- GitBook and docs preview: passed +- Prose/sweep checks: successful scope-gate no-ops, not substantive coverage 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. +- Installed? N/A — no `.gsd/gate.sh` exists. +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20 tests. +- `git diff --check`: passed. +- Word count: 481. -Files changed/artifacts produced: +Artifacts: - `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` -- `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` -- `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` -- `planning/adr-0016-code-review-752099a.md` -- `planning/adr-0016-verification-85fde83.md` -- `planning/adr-0016-verification-d09520e.md` -- `planning/adr-0016-verification-58545cd.md` -- `planning/adr-0016-adversarial-d18a63b.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 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: +- This checkpoint +- Exact-SHA reports matching `planning/adr-0016-*.md` -- ADR governance: passed, 1 ADR checked. -- Governance tests: 20 passed. -- Diff check: passed. -- 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. -- 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. -- 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`. -- 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`. -- Concise redraft `afdaa07` replaced the detailed decision; tightening commit `f326e0c` reduced the complete ADR to 477 words. ADR governance, 20 tests, diff check, and exact-head CI passed. -- Fresh concise-ADR code review at `752099a`: passed with no findings. Report: `planning/adr-0016-code-review-752099a.md`. -- Concise-ADR goal verification at `85fde83`: 11/12 goals verified; ADR content passed, while stale state and PR wording failed the evidence-accuracy goal. Report: `planning/adr-0016-verification-85fde83.md`. -- Reverification at `d09520e`: ADR content and earlier corrections passed; it found only the invalid recorded full `f326e0c` SHA and stale checkpoint review/next-step/CI wording. Those are corrected in this update. -- Final reverification at `58545cd`: passed 12/12 with no gaps. Report: `planning/adr-0016-verification-58545cd.md`. -- Adversarial review at `d18a63b`: READY-WITH-NITS with no blocking findings. Validation wording and stale PR-body nits were corrected. Report: `planning/adr-0016-adversarial-d18a63b.md`. - -## 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 for local review evidence - - 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 reverification head `d09520e` was green. - -## Ledger / forks - -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: latest concise-ADR review `752099ac110182655ec114a724eb236c66d4427e` -- Result: Passed with no findings after the scope reset -- 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. -- 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 were remediated in `4873f36` and re-reviewed at `481ca8c`. -- Re-review disposition at `481ca8c`: both findings resolved; code-review gate passed. -- Current report: `planning/adr-0016-code-review-752099a.md`; earlier reports are historical pre-reset evidence - -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`); no fresh attempt ran because adversarial review blocked advancement. +## Honesty Rules + +- No-harness-modification: Pass. No gate, CI, test, build, or environment change. +- Baseline-diff for evidence: Pass. No failure was dismissed. +- Evidence reproducible-from-branch: Pass. Review reports and audit are committed. +- Local vs CI consistency: Pass for applicable ADR checks. + +## Review Findings + +Code review: + +- Concise ADR review at `752099a`: passed with no findings. +- Focused evidence-wording review at `fc49173`: ADR passed; the old checkpoint had one MEDIUM consistency finding. +- Disposition: replaced the old accumulated checkpoint with this concise current record. + +Goal verification: + +- Final concise verification at `58545cd`: passed 12/12 with no gaps. +- Later ADR change: one validation line aligned with an already-authorized evidence path; focused code review passed it. Adversarial review: -- 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: Blockers -- Findings: - - 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. 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` -- 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` -- Scope-reset disposition: the journey, route, skill, and ADR-0011 decisions reviewed at `ef646b9` were removed from ADR-0016. Fresh review of the concise target decision is pending. +- Review at `d18a63b`: READY-WITH-NITS; no CRITICAL, HIGH, or MEDIUM findings. +- Deployed-network validation wording nit: corrected in `dfe2161` and passed focused review. +- Stale PR-body nit: corrected. Craft Review: -- Reviewer/tool: craft -- Required? Yes — repository-governance and maintainer-conformance work. -- 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. +- Required: Yes. +- Result: Not run; next gate after exact-head checkpoint review. + +Clean-context review: + +- Required: Yes. +- Result: Not run; follows Craft Review. + +## Drift / Scope Concerns -## Drift / scope concerns +The included v0.11.2 audit is historical motivation. A fresh release audit is required before implementation. ADR acceptance does not promote a release or authorize documentation changes. -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. +The branch is behind current `main`, but the PR merge ref is green. Any content-changing integration requires renewed review. -## Open questions / decisions for Jim +## Open Questions / Decisions for Jim -No owner decision is pending until exact-head revalidation, Craft, and clean-context complete. The redraft does not authorize merge or ADR acceptance. +No architecture decision is pending. Attended mode requires approval to rerun after the checkpoint correction. -PR / upstream action gate, if applicable: +PR / upstream action gate: -- PR ready to raise? Yes — as a draft CI/review vehicle only; not acceptance-ready or merge-ready -- 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. +- PR ready to raise? Already open as draft review/CI vehicle. +- Merge ready? No. +- Jim authorized merge? No. -## Recommended next step +## Recommended Next Step -Revalidate exact head after the one-line evidence correction, then run Craft and clean-context. Do not merge, accept ADR-0016, or begin implementation. +Rerun focused exact-head review of this checkpoint. If it passes, run Craft and clean-context. Then return to Jim for the ADR acceptance decision. Do not merge or implement. -## Handoff note +## Handoff Note -Jim replaced the detailed proposal with a concise target-architecture decision. Code review, CI, goal verification, and adversarial review are green. One adversarial wording nit was corrected in `dfe2161`; exact-head revalidation, Craft, and clean-context remain. No implementation is authorized. +The concise ADR, code review, goal verification, adversarial review, and CI are green. The checkpoint-consistency finding is corrected but not yet re-reviewed. Craft and clean-context remain. ADR-0016 is Proposed and implementation is unauthorized. From 9c07981552b64440eab2fc52419d7220a03055cd Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 20:55:52 +0100 Subject: [PATCH 37/50] docs(gsd): record ADR final review gates --- planning/STATE.md | 9 +++++--- planning/adr-0016-clean-context-dcf7c8c.md | 14 +++++++++++++ planning/adr-0016-craft-dcf7c8c.md | 19 +++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 24 +++++++++++++++------- 4 files changed, 56 insertions(+), 10 deletions(-) create mode 100644 planning/adr-0016-clean-context-dcf7c8c.md create mode 100644 planning/adr-0016-craft-dcf7c8c.md diff --git a/planning/STATE.md b/planning/STATE.md index 1956397..0a9bb66 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: reconcile concise ADR checkpoint before final gates -- Status: ADR passed focused review; checkpoint contradiction found; attended checkpoint +- Task: resolve clean-context panel activation +- Status: code, verification, adversarial, Craft, and CI passed; clean-context blocked - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -82,6 +82,9 @@ - LOW: PR body lagged final verification. Corrected after review. - Focused code review at `fc49173`: ADR content passed with no findings; one MEDIUM checkpoint-consistency issue remained. Report: `planning/adr-0016-code-review-fc49173.md`. - The accumulated checkpoint mixed current READY-WITH-NITS status with historical blocker/pending language. It is replaced by a concise current checkpoint; detailed history remains in the review reports. +- Exact-head focused checkpoint review at `dcf7c8c`: passed with no findings. +- Craft Review at `dcf7c8c`: passed with no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-craft-dcf7c8c.md`. +- Clean-context review at `dcf7c8c`: blocked before inference because the controlled Claude panel lacks the separate Milestone A activation verdict. No substitute was used. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -96,4 +99,4 @@ ## Next -- With Jim's attended approval, rerun focused exact-head review of the concise checkpoint, then run Craft and clean-context. Do not merge, accept the ADR, or begin implementation. +- Jim must either authorize the separate Milestone A panel activation, explicitly waive clean-context for this ADR, or stop pending panel activation. Do not merge, accept the ADR, or begin implementation. diff --git a/planning/adr-0016-clean-context-dcf7c8c.md b/planning/adr-0016-clean-context-dcf7c8c.md new file mode 100644 index 0000000..f564873 --- /dev/null +++ b/planning/adr-0016-clean-context-dcf7c8c.md @@ -0,0 +1,14 @@ +# ADR-0016 clean-context review — dcf7c8c + +- Date: 2026-08-28 +- Requested commit: `dcf7c8c5ca5199f174b5d493c3a75215933e3f4b` +- Requested reviewer: controlled Claude panel Fable lane +- Result: `Blocked` + +The reviewer was not invoked. The panel remains inactive for normal and ad-hoc use until Jim records the separate Milestone A activation verdict. The earlier Slice 2 proof authorization cannot be reused. + +No substitute reviewer was used and no inference command was attempted. + +Evidence line: + +`claude=official claude CLI Fable review family (Anthropic), BLOCKED: panel activation/dispatch authorization absent; no reviewer inference attempted` diff --git a/planning/adr-0016-craft-dcf7c8c.md b/planning/adr-0016-craft-dcf7c8c.md new file mode 100644 index 0000000..f480423 --- /dev/null +++ b/planning/adr-0016-craft-dcf7c8c.md @@ -0,0 +1,19 @@ +# ADR-0016 Craft Review — dcf7c8c + +- Date: 2026-08-28 +- Reviewed commit: `dcf7c8c5ca5199f174b5d493c3a75215933e3f4b` +- Current PR base: `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Reviewer: Craft — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `Pass` + +## Findings + +- CONFORMANCE: none. +- SIMPLICITY: none. +- NIT: none. + +ADR-0016 followed the repository template and governance, kept partial supersession precise, used American English, and remained concise. The larger branch footprint was attributable to historical audit and review evidence rather than speculative architecture or implementation. + +## Independence + +Fresh context, but the same model/provider as prior lanes. The implementer provider is unrecorded, so independence evidence is weaker. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index ee591d7..a62a299 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 -Revise — ADR content passed focused review, but the accumulated checkpoint contradicted the current review status. This file replaces it with the current state; exact-head review is pending. +Blocked — code review, verification, adversarial, Craft, and CI passed. Clean-context review could not invoke the controlled Claude panel because Milestone A activation is absent. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit -Unreviewed backlog: Craft and clean-context +Unreviewed backlog: clean-context only ## What happened @@ -62,6 +62,7 @@ Code review: - Concise ADR review at `752099a`: passed with no findings. - Focused evidence-wording review at `fc49173`: ADR passed; the old checkpoint had one MEDIUM consistency finding. - Disposition: replaced the old accumulated checkpoint with this concise current record. +- Focused review of the replacement checkpoint at `dcf7c8c`: passed with no findings. Goal verification: @@ -77,12 +78,17 @@ Adversarial review: Craft Review: - Required: Yes. -- Result: Not run; next gate after exact-head checkpoint review. +- Result: Pass at `dcf7c8c`; no CONFORMANCE, SIMPLICITY, or NIT findings. +- Report: `planning/adr-0016-craft-dcf7c8c.md`. Clean-context review: - Required: Yes. -- Result: Not run; follows Craft Review. +- Result: Blocked before inference. +- Reason: controlled Claude panel normal/ad-hoc use lacks Jim's separate Milestone A activation verdict. +- No substitute reviewer was used. +- Evidence: `claude=official claude CLI Fable review family (Anthropic), BLOCKED: panel activation/dispatch authorization absent; no reviewer inference attempted` +- Report: `planning/adr-0016-clean-context-dcf7c8c.md`. ## Drift / Scope Concerns @@ -92,7 +98,11 @@ The branch is behind current `main`, but the PR merge ref is green. Any content- ## Open Questions / Decisions for Jim -No architecture decision is pending. Attended mode requires approval to rerun after the checkpoint correction. +Choose one: + +1. Authorize the separate Milestone A panel activation so the controlled Claude review can run. +2. Explicitly waive clean-context for ADR-0016. +3. Stop pending panel activation. PR / upstream action gate: @@ -102,8 +112,8 @@ PR / upstream action gate: ## Recommended Next Step -Rerun focused exact-head review of this checkpoint. If it passes, run Craft and clean-context. Then return to Jim for the ADR acceptance decision. Do not merge or implement. +Resolve the clean-context activation decision. If review runs and passes, return to Jim for ADR acceptance. Do not merge or implement. ## Handoff Note -The concise ADR, code review, goal verification, adversarial review, and CI are green. The checkpoint-consistency finding is corrected but not yet re-reviewed. Craft and clean-context remain. ADR-0016 is Proposed and implementation is unauthorized. +The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Clean-context is blocked by panel activation policy. ADR-0016 remains Proposed and implementation is unauthorized. From d64a630d7ba6863bc46208c82c79a181a6b7b23a Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:04:59 +0100 Subject: [PATCH 38/50] docs(gsd): stop pending panel activation --- planning/STATE.md | 5 +++-- planning/gsd-adr-0016-checkpoint.md | 12 ++++-------- 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 0a9bb66..390a01b 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -5,7 +5,7 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation - Task: resolve clean-context panel activation -- Status: code, verification, adversarial, Craft, and CI passed; clean-context blocked +- Status: stopped pending separate Milestone A panel activation - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -85,6 +85,7 @@ - Exact-head focused checkpoint review at `dcf7c8c`: passed with no findings. - Craft Review at `dcf7c8c`: passed with no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-craft-dcf7c8c.md`. - Clean-context review at `dcf7c8c`: blocked before inference because the controlled Claude panel lacks the separate Milestone A activation verdict. No substitute was used. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. +- Jim chose `Stop pending activation` on 2026-08-28. Clean-context is not waived, panel activation is not authorized by this ADR, and the acceptance checkpoint remains blocked. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -99,4 +100,4 @@ ## Next -- Jim must either authorize the separate Milestone A panel activation, explicitly waive clean-context for this ADR, or stop pending panel activation. Do not merge, accept the ADR, or begin implementation. +- Stop. Resume only after the separate panel work records a Milestone A activation verdict, then run controlled Claude clean-context review before the ADR acceptance checkpoint. 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 a62a299..48081e9 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 -Blocked — code review, verification, adversarial, Craft, and CI passed. Clean-context review could not invoke the controlled Claude panel because Milestone A activation is absent. +Blocked — Jim chose to stop pending the separate Milestone A panel activation. Clean-context is not waived. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit @@ -98,11 +98,7 @@ The branch is behind current `main`, but the PR merge ref is green. Any content- ## Open Questions / Decisions for Jim -Choose one: - -1. Authorize the separate Milestone A panel activation so the controlled Claude review can run. -2. Explicitly waive clean-context for ADR-0016. -3. Stop pending panel activation. +Resolved owner decision: stop pending separate Milestone A panel activation. This ADR does not authorize panel activation or waive clean-context. PR / upstream action gate: @@ -112,8 +108,8 @@ PR / upstream action gate: ## Recommended Next Step -Resolve the clean-context activation decision. If review runs and passes, return to Jim for ADR acceptance. Do not merge or implement. +Stop. After a separate Milestone A activation verdict, run controlled Claude clean-context review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. ## Handoff Note -The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Clean-context is blocked by panel activation policy. ADR-0016 remains Proposed and implementation is unauthorized. +The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Jim chose to stop because clean-context is blocked by panel activation policy. ADR-0016 remains Proposed and implementation is unauthorized. From 50f4462ce7a99f82bd8af916f4120bef69580867 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:08:03 +0100 Subject: [PATCH 39/50] docs(gsd): record panel activation verdict --- planning/STATE.md | 7 ++++--- planning/gsd-adr-0016-checkpoint.md | 8 ++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 390a01b..1336b0f 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: resolve clean-context panel activation -- Status: stopped pending separate Milestone A panel activation +- Task: run controlled Claude clean-context review +- Status: Milestone A panel activation approved; clean-context dispatch pending - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -86,6 +86,7 @@ - Craft Review at `dcf7c8c`: passed with no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-craft-dcf7c8c.md`. - Clean-context review at `dcf7c8c`: blocked before inference because the controlled Claude panel lacks the separate Milestone A activation verdict. No substitute was used. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. - Jim chose `Stop pending activation` on 2026-08-28. Clean-context is not waived, panel activation is not authorized by this ADR, and the acceptance checkpoint remains blocked. +- Jim subsequently declared: `Milestone A panel activation approved for normal and ad-hoc controlled external reviews.` on 2026-08-28. This activates the controlled panel beyond PR #98; it does not authorize ADR acceptance, merge, or implementation. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -100,4 +101,4 @@ ## Next -- Stop. Resume only after the separate panel work records a Milestone A activation verdict, then run controlled Claude clean-context review before the ADR acceptance checkpoint. Do not merge, accept the ADR, or begin implementation. +- Dispatch a fresh controlled Claude Fable clean-context review for the current PR evidence. If it passes, return to Jim for the ADR acceptance decision. Do not merge or implement. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 48081e9..6575077 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 -Blocked — Jim chose to stop pending the separate Milestone A panel activation. Clean-context is not waived. +Continue — Jim approved Milestone A panel activation for normal and ad-hoc controlled external reviews. Clean-context dispatch is pending. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit @@ -98,7 +98,7 @@ The branch is behind current `main`, but the PR merge ref is green. Any content- ## Open Questions / Decisions for Jim -Resolved owner decision: stop pending separate Milestone A panel activation. This ADR does not authorize panel activation or waive clean-context. +Resolved owner decision: `Milestone A panel activation approved for normal and ad-hoc controlled external reviews.` This does not authorize ADR acceptance, merge, or implementation. PR / upstream action gate: @@ -108,8 +108,8 @@ PR / upstream action gate: ## Recommended Next Step -Stop. After a separate Milestone A activation verdict, run controlled Claude clean-context review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. +Run a fresh controlled Claude Fable clean-context review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. ## Handoff Note -The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Jim chose to stop because clean-context is blocked by panel activation policy. ADR-0016 remains Proposed and implementation is unauthorized. +The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Milestone A panel activation is now approved; clean-context remains to run. ADR-0016 remains Proposed and implementation is unauthorized. From 0df9bfd85650a57a84f69264f1e7cf15df4d2ac9 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:11:52 +0100 Subject: [PATCH 40/50] docs(gsd): record panel brief blocker --- planning/STATE.md | 7 +++++-- planning/adr-0016-clean-context-50f4462.md | 16 ++++++++++++++++ planning/gsd-adr-0016-checkpoint.md | 10 +++++++--- 3 files changed, 28 insertions(+), 5 deletions(-) create mode 100644 planning/adr-0016-clean-context-50f4462.md diff --git a/planning/STATE.md b/planning/STATE.md index 1336b0f..6233c84 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -5,7 +5,7 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation - Task: run controlled Claude clean-context review -- Status: Milestone A panel activation approved; clean-context dispatch pending +- Status: Milestone A activated; clean-context blocked on caller-owned brief creation permission - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -87,6 +87,9 @@ - Clean-context review at `dcf7c8c`: blocked before inference because the controlled Claude panel lacks the separate Milestone A activation verdict. No substitute was used. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. - Jim chose `Stop pending activation` on 2026-08-28. Clean-context is not waived, panel activation is not authorized by this ADR, and the acceptance checkpoint remains blocked. - Jim subsequently declared: `Milestone A panel activation approved for normal and ad-hoc controlled external reviews.` on 2026-08-28. This activates the controlled panel beyond PR #98; it does not authorize ADR acceptance, merge, or implementation. +- Activated dispatch attempt for evidence revision `50f4462` was blocked before inference because the required caller-owned disposable root and `brief.md` could not be created under the orchestrator's outer filesystem permission. No model ran. Report: `planning/adr-0016-clean-context-50f4462.md`. + - `models: provider=not-observed · model=not-resolved · duration=unknown` + - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -101,4 +104,4 @@ ## Next -- Dispatch a fresh controlled Claude Fable clean-context review for the current PR evidence. If it passes, return to Jim for the ADR acceptance decision. Do not merge or implement. +- Obtain Jim's explicit authorization to create one disposable caller-owned panel root and regular brief under `/var/folders/f_/j942sskj6nx67b6gk3rqgsqm0000gn/T/opencode/`, then make a fresh controlled Claude dispatch. Do not merge, accept, or implement. diff --git a/planning/adr-0016-clean-context-50f4462.md b/planning/adr-0016-clean-context-50f4462.md new file mode 100644 index 0000000..326dccb --- /dev/null +++ b/planning/adr-0016-clean-context-50f4462.md @@ -0,0 +1,16 @@ +# ADR-0016 clean-context dispatch — 50f4462 + +- Date: 2026-08-28 +- Requested commit: `50f4462` +- Requested reviewer: controlled Claude Fable panel lane +- Result: `Blocked before inference` + +Milestone A activation was present in `planning/STATE.md`, but the required caller-owned `brief.md` did not exist under the exact disposable panel root. The orchestrator's outer filesystem permission refused creation of that root and brief. Chat text cannot substitute for the required regular stdin file. + +The panel could not create or attest the caller-owned brief. Claude CLI and inference were not invoked. No session, provider/model attribution, findings, or persisted output exists. + +Required next action: explicitly authorize creation of one disposable root and regular `brief.md` under the named `/var/.../opencode/gsd-panel-` path, then issue a fresh dispatch with all fields. + +models: provider=not-observed · model=not-resolved · duration=unknown + +claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 6575077..6868f23 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 approved Milestone A panel activation for normal and ad-hoc controlled external reviews. Clean-context dispatch is pending. +Blocked — Milestone A is active, but clean-context cannot run until the orchestrator may create the required disposable caller-owned root and brief. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit @@ -89,6 +89,10 @@ Clean-context review: - No substitute reviewer was used. - Evidence: `claude=official claude CLI Fable review family (Anthropic), BLOCKED: panel activation/dispatch authorization absent; no reviewer inference attempted` - Report: `planning/adr-0016-clean-context-dcf7c8c.md`. +- Activated retry at revision `50f4462`: blocked before inference because the caller-owned root/brief was missing and outer filesystem permission refused creation. +- `models: provider=not-observed · model=not-resolved · duration=unknown` +- `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` +- Report: `planning/adr-0016-clean-context-50f4462.md`. ## Drift / Scope Concerns @@ -98,7 +102,7 @@ The branch is behind current `main`, but the PR merge ref is green. Any content- ## Open Questions / Decisions for Jim -Resolved owner decision: `Milestone A panel activation approved for normal and ad-hoc controlled external reviews.` This does not authorize ADR acceptance, merge, or implementation. +Milestone A activation is resolved. A narrower runtime permission remains: authorize one disposable caller-owned panel root and regular brief under the approved temporary path. This does not authorize ADR acceptance, merge, or implementation. PR / upstream action gate: @@ -108,7 +112,7 @@ PR / upstream action gate: ## Recommended Next Step -Run a fresh controlled Claude Fable clean-context review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. +After explicit disposable-root permission, create and attest the brief, then run a fresh controlled Claude Fable review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. ## Handoff Note From 1c8bd255e744e911fb2ae8985fb96669c41f6856 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Sat, 29 Aug 2026 08:16:08 +0100 Subject: [PATCH 41/50] docs(gsd): record panel harness blocker --- planning/STATE.md | 5 +++-- planning/gsd-adr-0016-checkpoint.md | 8 ++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index 6233c84..c6a83e6 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -5,7 +5,7 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation - Task: run controlled Claude clean-context review -- Status: Milestone A activated; clean-context blocked on caller-owned brief creation permission +- Status: clean-context blocked by static outer-harness filesystem deny - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -90,6 +90,7 @@ - Activated dispatch attempt for evidence revision `50f4462` was blocked before inference because the required caller-owned disposable root and `brief.md` could not be created under the orchestrator's outer filesystem permission. No model ran. Report: `planning/adr-0016-clean-context-50f4462.md`. - `models: provider=not-observed · model=not-resolved · duration=unknown` - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` +- Jim explicitly authorized creation of disposable root `gsd-panel-a1ae9d0a-d513-47f5-8266-b006db956517` and a credential-free brief of at most 16 KiB for revision `0df9bfd`. The outer harness still denied the exact `mkdir` call because its final static external-directory deny overrides the authorization. This is now a mechanism-level blocker; no model ran. - 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -104,4 +105,4 @@ ## Next -- Obtain Jim's explicit authorization to create one disposable caller-owned panel root and regular brief under `/var/folders/f_/j942sskj6nx67b6gk3rqgsqm0000gn/T/opencode/`, then make a fresh controlled Claude dispatch. Do not merge, accept, or implement. +- Stop. The outer harness permission must be corrected outside this project run, or Jim must manually create and attest the disposable root/brief. Then make a fresh controlled Claude dispatch. Do not merge, accept, or implement. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 6868f23..eba3c60 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 -Blocked — Milestone A is active, but clean-context cannot run until the orchestrator may create the required disposable caller-owned root and brief. +Blocked — Milestone A and exact root permission are approved, but the outer harness's final static external-directory deny prevents creating the required caller-owned root and brief. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit @@ -102,7 +102,7 @@ The branch is behind current `main`, but the PR merge ref is green. Any content- ## Open Questions / Decisions for Jim -Milestone A activation is resolved. A narrower runtime permission remains: authorize one disposable caller-owned panel root and regular brief under the approved temporary path. This does not authorize ADR acceptance, merge, or implementation. +Milestone A activation and the narrow disposable-root authorization are resolved. The remaining blocker is static harness permission, not owner intent. This does not authorize ADR acceptance, merge, or implementation. PR / upstream action gate: @@ -112,8 +112,8 @@ PR / upstream action gate: ## Recommended Next Step -After explicit disposable-root permission, create and attest the brief, then run a fresh controlled Claude Fable review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. +Stop. Correct the outer harness permission outside this project run, or have Jim manually create and attest the root/brief. Then run a fresh controlled Claude Fable review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. ## Handoff Note -The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Milestone A panel activation is now approved; clean-context remains to run. ADR-0016 remains Proposed and implementation is unauthorized. +The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Clean-context remains blocked by static outer-harness filesystem permission despite explicit activation and root authorization. ADR-0016 remains Proposed and implementation is unauthorized. From f3f3bdc735d5357ea4a03741163a800510a8b61c Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Sat, 29 Aug 2026 08:18:57 +0100 Subject: [PATCH 42/50] docs(gsd): record ADR clean-context waiver --- planning/STATE.md | 7 ++++--- planning/gsd-adr-0016-checkpoint.md | 11 ++++++----- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index c6a83e6..c6851e7 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: run controlled Claude clean-context review -- Status: clean-context blocked by static outer-harness filesystem deny +- Task: human acceptance decision for Proposed ADR-0016 +- Status: acceptance-ready; clean-context explicitly waived by Jim - Mode: attended - Branch: `adr/released-and-usable-truth` - Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 @@ -91,6 +91,7 @@ - `models: provider=not-observed · model=not-resolved · duration=unknown` - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` - Jim explicitly authorized creation of disposable root `gsd-panel-a1ae9d0a-d513-47f5-8266-b006db956517` and a credential-free brief of at most 16 KiB for revision `0df9bfd`. The outer harness still denied the exact `mkdir` call because its final static external-directory deny overrides the authorization. This is now a mechanism-level blocker; no model ran. +- Jim declared `waive and present` on 2026-08-28. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. - Clean-context 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. @@ -105,4 +106,4 @@ ## Next -- Stop. The outer harness permission must be corrected outside this project run, or Jim must manually create and attest the disposable root/brief. Then make a fresh controlled Claude dispatch. Do not merge, accept, or implement. +- Present Proposed ADR-0016 to Jim for explicit acceptance or rejection. Do not mark it Accepted, merge, or implement without the corresponding human decisions. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index eba3c60..d0a72b6 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 -Blocked — Milestone A and exact root permission are approved, but the outer harness's final static external-directory deny prevents creating the required caller-owned root and brief. +Stop for decision — all completed gates pass and Jim explicitly waived clean-context for ADR-0016. The Proposed ADR is ready for human acceptance or rejection. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit -Unreviewed backlog: clean-context only +Unreviewed backlog: none; clean-context is explicitly Jim-waived for this ADR ## What happened @@ -93,6 +93,7 @@ Clean-context review: - `models: provider=not-observed · model=not-resolved · duration=unknown` - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` - Report: `planning/adr-0016-clean-context-50f4462.md`. +- Final disposition: Not run; Jim explicitly declared `waive and present` on 2026-08-28 after the controlled panel failed before inference. This waiver applies only to ADR-0016. ## Drift / Scope Concerns @@ -102,7 +103,7 @@ The branch is behind current `main`, but the PR merge ref is green. Any content- ## Open Questions / Decisions for Jim -Milestone A activation and the narrow disposable-root authorization are resolved. The remaining blocker is static harness permission, not owner intent. This does not authorize ADR acceptance, merge, or implementation. +Accept or reject Proposed ADR-0016. The clean-context waiver does not itself accept the ADR or authorize merge or implementation. PR / upstream action gate: @@ -112,8 +113,8 @@ PR / upstream action gate: ## Recommended Next Step -Stop. Correct the outer harness permission outside this project run, or have Jim manually create and attest the root/brief. Then run a fresh controlled Claude Fable review. If it passes, return to Jim for ADR acceptance. Do not merge or implement. +Jim decides whether to accept Proposed ADR-0016. If accepted, a human-authorized status change and later merge decision remain separate. Do not implement yet. ## Handoff Note -The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Clean-context remains blocked by static outer-harness filesystem permission despite explicit activation and root authorization. ADR-0016 remains Proposed and implementation is unauthorized. +The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Clean-context is explicitly waived for this ADR. ADR-0016 remains Proposed until Jim decides; merge and implementation remain unauthorized. From 7b8b53722d3632b94d83a29b5712d78ebb3a6c4e Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Sat, 29 Aug 2026 11:26:32 +0100 Subject: [PATCH 43/50] docs(adr-0016): repair evidence integrity - Correct audit refs and preserve local-only provenance honestly - Reconcile PR, review, waiver, and CI state --- planning/STATE.md | 18 ++++----- planning/gsd-adr-0016-checkpoint.md | 54 +++++++++++++------------ planning/released-antd-v0.11.2-audit.md | 8 ++-- 3 files changed, 41 insertions(+), 39 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index c6851e7..f20e271 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,13 +4,13 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: human acceptance decision for Proposed ADR-0016 -- Status: acceptance-ready; clean-context explicitly waived by Jim +- Task: evidence-integrity remediation review for Proposed ADR-0016 +- Status: evidence remediation under review; fresh review and exact-head CI are required before the acceptance decision - Mode: attended - Branch: `adr/released-and-usable-truth` -- Draft PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 +- PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) - Branch point: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` -- Current draft-PR base: `origin/main` at `49e202c818bab1be780b81c28e5d0718cfb89b1c` +- Current PR base: `origin/main` at `49e202c818bab1be780b81c28e5d0718cfb89b1c` - Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; tightening `f326e0c3f65de0646495da02d6eb74b70dac966f`; evidence-alignment correction `dfe2161` - Implementation: not started; ADR acceptance remains human-only @@ -92,9 +92,8 @@ - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` - Jim explicitly authorized creation of disposable root `gsd-panel-a1ae9d0a-d513-47f5-8266-b006db956517` and a credential-free brief of at most 16 KiB for revision `0df9bfd`. The outer harness still denied the exact `mkdir` call because its final static external-directory deny overrides the authorization. This is now a mechanism-level blocker; no model ran. - Jim declared `waive and present` on 2026-08-28. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. -- Clean-context 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 reverification head `d09520e` passed ADR Governance run `33189218449` and both GitBook checks. Prose/sweep checks returned success as scope-gate no-ops, not substantive coverage. +- Clean-context controlling disposition: Jim's one-off waiver follows the blocked-before-inference controlled-panel sequence above; no same-model substitute ran. +- CI arbiter: required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`, ADR Governance run `33245584910` job `99082354387`, prose run `33245584905` job `99082354434`, sweep run `33245584892` job `99082354463`, and reachability run `33245584906` job `99082354330` passed; both GitBook statuses also passed. This is historical pre-remediation evidence. New remediation commits require fresh exact-head CI. - 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 @@ -102,8 +101,9 @@ - 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. +- Do not merge PR #98 without Jim's explicit confirmation. ## Next -- Present Proposed ADR-0016 to Jim for explicit acceptance or rejection. Do not mark it Accepted, merge, or implement without the corresponding human decisions. +- Complete review and fresh exact-head CI for the evidence remediation. +- If those gates pass, present Proposed ADR-0016 to Jim for explicit acceptance or rejection. ADR acceptance, merge, and implementation remain unauthorized. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index d0a72b6..3903680 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -1,18 +1,18 @@ # GSD Checkpoint — Concise Proposed ADR-0016 -Date: 2026-08-28 +Date: 2026-08-29 Project: Autonomi Developer Documentation Slice/question: Should public documentation describe only stable software the public can obtain? Prepared by: orchestrator -Agents/tools used: operative, codereviewer, verifier, adversarial; Craft and clean-context pending +Agents/tools used: operative, codereviewer, verifier, adversarial, Craft (passed); clean-context Jim-waived for ADR-0016 ## Status -Stop for decision — all completed gates pass and Jim explicitly waived clean-context for ADR-0016. The Proposed ADR is ready for human acceptance or rejection. +Revise — ADR substance passed, but its evidence remediation remains under review until fresh review and exact-head CI pass. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. Review cadence: per-unit -Unreviewed backlog: none; clean-context is explicitly Jim-waived for this ADR +Unreviewed backlog: this evidence remediation requires fresh review and exact-head CI; clean-context is explicitly Jim-waived for ADR-0016 ## What happened @@ -26,17 +26,22 @@ ADR-0016 remains Proposed. No implementation, rendered docs, skill, CI, test, or CI arbiter / green of record: -- Location: draft PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 -- Exact reviewed head: `fc49173dc040425429a4cc298eb3811a23650b5a` -- ADR Governance run `33204071304`, job `98960532646`: passed -- GitBook and docs preview: passed -- Prose/sweep checks: successful scope-gate no-ops, not substantive coverage +- Location: PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) +- Rule: required checks on the current PR head are the green of record. +- Historical pre-remediation head: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`. +- ADR Governance run `33245584910`, job `99082354387`: passed. +- Prose run `33245584905`, job `99082354434`: passed as a scope-gate no-op. +- Sweep run `33245584892`, job `99082354463`: passed as a scope-gate no-op. +- Reachability run `33245584906`, job `99082354330`: passed. +- Both GitBook statuses: passed. +- These checks are historical pre-remediation evidence. The evidence-repair commit requires fresh exact-head CI. Local fast gate / `.gsd/gate.sh`: - Installed? N/A — no `.gsd/gate.sh` exists. - ADR governance: passed, 1 ADR checked. - Governance tests: passed, 20 tests. +- ant-sdk blob ref length check: passed, 31 refs checked and all are 40 characters. - `git diff --check`: passed. - Word count: 481. @@ -53,7 +58,7 @@ Artifacts: - No-harness-modification: Pass. No gate, CI, test, build, or environment change. - Baseline-diff for evidence: Pass. No failure was dismissed. - Evidence reproducible-from-branch: Pass. Review reports and audit are committed. -- Local vs CI consistency: Pass for applicable ADR checks. +- Local vs CI consistency: Pending. Pre-remediation checks passed; the evidence-repair commit requires fresh exact-head CI. ## Review Findings @@ -84,37 +89,34 @@ Craft Review: Clean-context review: - Required: Yes. -- Result: Blocked before inference. -- Reason: controlled Claude panel normal/ad-hoc use lacks Jim's separate Milestone A activation verdict. -- No substitute reviewer was used. -- Evidence: `claude=official claude CLI Fable review family (Anthropic), BLOCKED: panel activation/dispatch authorization absent; no reviewer inference attempted` -- Report: `planning/adr-0016-clean-context-dcf7c8c.md`. -- Activated retry at revision `50f4462`: blocked before inference because the caller-owned root/brief was missing and outer filesystem permission refused creation. -- `models: provider=not-observed · model=not-resolved · duration=unknown` -- `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` -- Report: `planning/adr-0016-clean-context-50f4462.md`. -- Final disposition: Not run; Jim explicitly declared `waive and present` on 2026-08-28 after the controlled panel failed before inference. This waiver applies only to ADR-0016. +- Result: Not run — one-off Jim waiver after the controlled panel attempts were blocked before inference. +- Initial attempt at `dcf7c8c`: blocked before inference because the separate Milestone A activation verdict was absent. Report: `planning/adr-0016-clean-context-dcf7c8c.md`. +- Jim later activated normal and ad-hoc controlled external reviews; activation absence is no longer the current blocker. +- Post-activation attempt at `50f4462`: blocked before inference because the caller-owned disposable root and `brief.md` were missing and the outer filesystem mechanism refused their creation. Report: `planning/adr-0016-clean-context-50f4462.md`. +- Jim then authorized the credential-free brief and disposable root for revision `0df9bfd`; the outer harness's static external-directory denial still blocked creation before inference. +- No model ran, and no same-model substitute review was used. +- Final disposition: Not run; Jim explicitly declared `waive and present` on 2026-08-28 after the controlled panel attempts failed before inference. This one-off waiver applies only to ADR-0016. ## Drift / Scope Concerns The included v0.11.2 audit is historical motivation. A fresh release audit is required before implementation. ADR acceptance does not promote a release or authorize documentation changes. -The branch is behind current `main`, but the PR merge ref is green. Any content-changing integration requires renewed review. +Merge commit `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` integrated current base `49e202c818bab1be780b81c28e5d0718cfb89b1c`. Any future content-changing integration requires renewed review. ## Open Questions / Decisions for Jim -Accept or reject Proposed ADR-0016. The clean-context waiver does not itself accept the ADR or authorize merge or implementation. +The acceptance decision waits for the evidence remediation's fresh review and exact-head CI. The clean-context waiver does not itself accept the ADR or authorize merge or implementation. PR / upstream action gate: -- PR ready to raise? Already open as draft review/CI vehicle. -- Merge ready? No. +- PR status: already open and non-draft. +- Merge ready? No; the evidence remediation requires fresh review and exact-head CI. - Jim authorized merge? No. ## Recommended Next Step -Jim decides whether to accept Proposed ADR-0016. If accepted, a human-authorized status change and later merge decision remain separate. Do not implement yet. +Rerun checks, review, and exact-head CI for this evidence repair, then present Proposed ADR-0016 for the acceptance decision. Acceptance, merge, and implementation remain separate unauthorized actions. ## Handoff Note -The concise ADR, code review, goal verification, adversarial review, Craft Review, and CI are green. Clean-context is explicitly waived for this ADR. ADR-0016 remains Proposed until Jim decides; merge and implementation remain unauthorized. +The concise ADR's substance passed code review, goal verification, adversarial review, and Craft Review. Clean-context is explicitly waived for ADR-0016. The evidence repair now requires fresh review and exact-head CI before the acceptance decision; ADR-0016 remains Proposed, and acceptance, merge, and implementation remain unauthorized. diff --git a/planning/released-antd-v0.11.2-audit.md b/planning/released-antd-v0.11.2-audit.md index 4237d47..02837c1 100644 --- a/planning/released-antd-v0.11.2-audit.md +++ b/planning/released-antd-v0.11.2-audit.md @@ -2,13 +2,13 @@ - 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 +- Emergency branch baseline: `2e11cdc908a04d31bc35a6d998211cdb7949ce93` on `docs/released-antd-safety`, before this audit commit; this local-only historical identifier is unavailable from the remote +- Original audit commit: `16bdb4de6dc6a109b70238b31956685db839318d`; this local-only historical identifier is unavailable from the remote, and the committed branch-local copy of this audit is the reproducible review artifact - Audit mode: attended knowledge-work checkpoint; no implementation or PR action is authorized ## Snapshot status -This is the dated motivating snapshot recorded on 2026-08-11. Its technical findings, exact 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. +This is the dated motivating snapshot recorded on 2026-08-11. Its technical findings, exact technical source refs, source links, and evidence limits remain inspectable evidence for Proposed ADR-0016. Its source-of-truth analysis, target-manifest application, recommended remediation, and statements about whether an ADR existed record the policy position before ADR-0016 was proposed. They are preserved as historical context, not as current policy or authorization. ## Executive verdict @@ -90,7 +90,7 @@ Ordinary MCP writes use the Python REST client's normal data/file operations and - **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 REST:** the daemon returns `payment_type: "wave_batch"` with payments or `payment_type: "merkle"` with depth, pool commitments, and timestamp. Finalize requires the matching `tx_hashes` or `winner_pool_hash`: [`upload.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/upload.rs#L24-L114) and [`upload.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/upload.rs#L194-L356). - **Raw gRPC:** the proto uses the same `"wave_batch"`/`"merkle"` discriminator and typed fields: [`upload.proto`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/proto/antd/v1/upload.proto#L9-L145). However, when all prepared chunks are already stored, core returns a valid empty wave-batch intent and accepts no-payment finalization, while the gRPC handler removes the pending upload and then rejects the empty `tx_hashes` map. The request fails, the `upload_id` is consumed, and no DataMap result is returned. REST accepts a present empty `tx_hashes` object. Sources: [`file.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/file.rs#L1554-L1562), [`batch.rs`](https://github.com/WithAutonomi/ant-client/blob/3e6bdd28f5af3c7601ca919640bf8dfccf4f8d6b/ant-core/src/data/client/batch.rs#L337-L342), [`grpc/service.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/grpc/service.rs#L1078-L1107), and [`rest/upload.rs`](https://github.com/WithAutonomi/ant-sdk/blob/3264b514dac9ed361a7426d6d6d5ae6a8e7b6b15/antd/src/rest/upload.rs#L223-L267). This is tracked upstream in [`ant-sdk` issue #233](https://github.com/WithAutonomi/ant-sdk/issues/233). The raw prepare contracts and ordinary paths are source-correct, but the gRPC finalize edge case above is defective. No funded daemon E2E exercises the complete contracts. From 6e9f0562b4d438eb110302db37e4b153b51656db Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Sat, 29 Aug 2026 12:16:46 +0100 Subject: [PATCH 44/50] docs(adr-0016): remove unreachable audit commands - Remove remote compare calls to a local-only historical commit - Record the HIGH review finding and pending re-review and CI --- planning/STATE.md | 1 + planning/gsd-adr-0016-checkpoint.md | 3 ++- planning/released-antd-v0.11.2-audit.md | 8 ++------ 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index f20e271..cb02cbd 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -94,6 +94,7 @@ - Jim declared `waive and present` on 2026-08-28. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. - Clean-context controlling disposition: Jim's one-off waiver follows the blocked-before-inference controlled-panel sequence above; no same-model substitute ran. - CI arbiter: required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`, ADR Governance run `33245584910` job `99082354387`, prose run `33245584905` job `99082354434`, sweep run `33245584892` job `99082354463`, and reachability run `33245584906` job `99082354330` passed; both GitBook statuses also passed. This is historical pre-remediation evidence. New remediation commits require fresh exact-head CI. +- Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. This correction removes those commands; fresh re-review and exact-head CI remain pending. - 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 diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 3903680..288e266 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -57,7 +57,7 @@ Artifacts: - No-harness-modification: Pass. No gate, CI, test, build, or environment change. - Baseline-diff for evidence: Pass. No failure was dismissed. -- Evidence reproducible-from-branch: Pass. Review reports and audit are committed. +- Evidence reproducible-from-branch: Pending. This correction removes the known unreachable commands; fresh re-review remains pending. - Local vs CI consistency: Pending. Pre-remediation checks passed; the evidence-repair commit requires fresh exact-head CI. ## Review Findings @@ -68,6 +68,7 @@ Code review: - Focused evidence-wording review at `fc49173`: ADR passed; the old checkpoint had one MEDIUM consistency finding. - Disposition: replaced the old accumulated checkpoint with this concise current record. - Focused review of the replacement checkpoint at `dcf7c8c`: passed with no findings. +- Attended code review of `7b8b537`: HIGH evidence-reproducibility finding; two GitHub compare calls in the audit targeted local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93` and failed remotely. This correction removes the unreachable commands; fresh re-review and exact-head CI remain pending. Goal verification: diff --git a/planning/released-antd-v0.11.2-audit.md b/planning/released-antd-v0.11.2-audit.md index 02837c1..49dc66c 100644 --- a/planning/released-antd-v0.11.2-audit.md +++ b/planning/released-antd-v0.11.2-audit.md @@ -221,6 +221,8 @@ No PR, push, merge, publish, release, rendered-doc edit, source edit, CI edit, t Representative commands used for the audit follow. They require `gh`, `curl`, and public network access; none changes repository state. +The original audit also used a local comparison against `2e11cdc908a04d31bc35a6d998211cdb7949ce93` while that commit was available locally. That comparison is no longer remotely reproducible and is not readiness evidence. This committed audit copy preserves the historical findings. + ```bash gh release view v0.11.2 --repo WithAutonomi/ant-sdk \ --json tagName,publishedAt,isDraft,isPrerelease,targetCommitish,assets,url @@ -245,12 +247,6 @@ 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. From 109101669908e7c7d86b3dc586a9b5b17933d2d6 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 31 Aug 2026 09:50:24 +0100 Subject: [PATCH 45/50] docs(adr-0016): correct review evidence record - Mark scope-gated CI jobs as non-substantive no-ops - Anchor the clean-context waiver record to its dated commit --- planning/STATE.md | 12 ++++++++++-- planning/gsd-adr-0016-checkpoint.md | 14 ++++++++------ 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index cb02cbd..69e7396 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -91,10 +91,18 @@ - `models: provider=not-observed · model=not-resolved · duration=unknown` - `claude=blocked-before-inference (caller-owned brief missing) · provider=not-observed · model=not-resolved` - Jim explicitly authorized creation of disposable root `gsd-panel-a1ae9d0a-d513-47f5-8266-b006db956517` and a credential-free brief of at most 16 KiB for revision `0df9bfd`. The outer harness still denied the exact `mkdir` call because its final static external-directory deny overrides the authorization. This is now a mechanism-level blocker; no model ran. -- Jim declared `waive and present` on 2026-08-28. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. +- Jim's `waive and present` declaration was recorded in commit `f3f3bdc735d5357ea4a03741163a800510a8b61c` on 2026-08-29. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. - Clean-context controlling disposition: Jim's one-off waiver follows the blocked-before-inference controlled-panel sequence above; no same-model substitute ran. -- CI arbiter: required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`, ADR Governance run `33245584910` job `99082354387`, prose run `33245584905` job `99082354434`, sweep run `33245584892` job `99082354463`, and reachability run `33245584906` job `99082354330` passed; both GitBook statuses also passed. This is historical pre-remediation evidence. New remediation commits require fresh exact-head CI. +- CI arbiter: required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: + - ADR Governance run `33245584910`, job `99082354387`, passed substantively; checkout, regression tests, and governance checks ran successfully. + - Prose run `33245584905`, job `99082354434`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main prose validation were skipped. + - Sweep run `33245584892`, job `99082354463`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main metadata-envelope validation were skipped. + - Sweep SHA reachability run `33245584906`, job `99082354330`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. + - GitBook status `GitBook`: passed. + - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. +- These results are historical pre-remediation evidence. New remediation commits require fresh exact-head CI. - Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. This correction removes those commands; fresh re-review and exact-head CI remain pending. +- Re-review of `6e9f056` found a MEDIUM CI-scope record issue and a LOW clean-context waiver-date record issue. This correction records the three scope-gated jobs as successful no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; fresh review and exact-head CI remain pending. - 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 diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 288e266..bb4f8e5 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -29,11 +29,12 @@ CI arbiter / green of record: - Location: PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) - Rule: required checks on the current PR head are the green of record. - Historical pre-remediation head: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`. -- ADR Governance run `33245584910`, job `99082354387`: passed. -- Prose run `33245584905`, job `99082354434`: passed as a scope-gate no-op. -- Sweep run `33245584892`, job `99082354463`: passed as a scope-gate no-op. -- Reachability run `33245584906`, job `99082354330`: passed. -- Both GitBook statuses: passed. +- ADR Governance run `33245584910`, job `99082354387`: passed substantively; checkout, regression tests, and governance checks ran successfully. +- Prose run `33245584905`, job `99082354434`: successful scope-gate no-op (`not applicable`); checkout, setup, and the main prose validation were skipped. +- Sweep run `33245584892`, job `99082354463`: successful scope-gate no-op (`not applicable`); checkout, setup, and the main metadata-envelope validation were skipped. +- Sweep SHA reachability run `33245584906`, job `99082354330`: successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. +- GitBook status `GitBook`: passed. +- GitBook status `GitBook - docs.autonomi.com/developers/`: passed. - These checks are historical pre-remediation evidence. The evidence-repair commit requires fresh exact-head CI. Local fast gate / `.gsd/gate.sh`: @@ -69,6 +70,7 @@ Code review: - Disposition: replaced the old accumulated checkpoint with this concise current record. - Focused review of the replacement checkpoint at `dcf7c8c`: passed with no findings. - Attended code review of `7b8b537`: HIGH evidence-reproducibility finding; two GitHub compare calls in the audit targeted local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93` and failed remotely. This correction removes the unreachable commands; fresh re-review and exact-head CI remain pending. +- Re-review of `6e9f056`: MEDIUM CI-scope record issue and LOW clean-context waiver-date record issue. This correction records prose, sweep, and sweep SHA reachability as successful scope-gate no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; fresh review and exact-head CI remain pending. Goal verification: @@ -96,7 +98,7 @@ Clean-context review: - Post-activation attempt at `50f4462`: blocked before inference because the caller-owned disposable root and `brief.md` were missing and the outer filesystem mechanism refused their creation. Report: `planning/adr-0016-clean-context-50f4462.md`. - Jim then authorized the credential-free brief and disposable root for revision `0df9bfd`; the outer harness's static external-directory denial still blocked creation before inference. - No model ran, and no same-model substitute review was used. -- Final disposition: Not run; Jim explicitly declared `waive and present` on 2026-08-28 after the controlled panel attempts failed before inference. This one-off waiver applies only to ADR-0016. +- Final disposition: Not run; Jim's `waive and present` declaration was recorded in commit `f3f3bdc735d5357ea4a03741163a800510a8b61c` on 2026-08-29 after the controlled panel attempts failed before inference. This one-off waiver applies only to ADR-0016. ## Drift / Scope Concerns From fda23c7d90611fc9ca2a37f7f053271c5a24531b Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 31 Aug 2026 10:55:34 +0100 Subject: [PATCH 46/50] docs(adr-0016): finalize branch-local evidence - Add final remediation review and verification reports - Condition acceptance presentation on current-head checks --- planning/STATE.md | 24 ++++++----- ...vidence-remediation-adversarial-1091016.md | 35 ++++++++++++++++ ...vidence-remediation-code-review-1091016.md | 14 +++++++ ...0016-evidence-remediation-craft-1091016.md | 21 ++++++++++ ...idence-remediation-verification-1091016.md | 26 ++++++++++++ planning/gsd-adr-0016-checkpoint.md | 40 ++++++++++--------- 6 files changed, 133 insertions(+), 27 deletions(-) create mode 100644 planning/adr-0016-evidence-remediation-adversarial-1091016.md create mode 100644 planning/adr-0016-evidence-remediation-code-review-1091016.md create mode 100644 planning/adr-0016-evidence-remediation-craft-1091016.md create mode 100644 planning/adr-0016-evidence-remediation-verification-1091016.md diff --git a/planning/STATE.md b/planning/STATE.md index 69e7396..d6653c9 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: evidence-integrity remediation review for Proposed ADR-0016 -- Status: evidence remediation under review; fresh review and exact-head CI are required before the acceptance decision +- Task: human acceptance decision for Proposed ADR-0016 after final current-PR-head checks +- Status: acceptance-ready when required checks attached to the current PR head are green; clean-context is explicitly waived for this ADR - Mode: attended - Branch: `adr/released-and-usable-truth` - PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) @@ -58,7 +58,7 @@ - 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. +- Journey-local amendment `fb00f10` formalizes that decision, including same-interface complete routes, global set selection/fallback, atomic optional-journey regression disclosure, journey-keyed manifest/docs/skill parity, and the minimum end-to-end store-and-retrieve outcome. Local ADR governance and 20 tests passed; PR CI and GitBook checks were green for that revision. - Exact-head adversarial re-review remained pending after the journey-local amendment. - Exact-head code review at `b1e4846`: passed with no findings and all qualification truth-table scenarios passed. Report: `planning/adr-0016-code-review-b1e4846.md`. - Exact-head goal verification at `39e2cdf`: passed, 10/10 goals and all required truth-table scenarios verified with no gaps. Report: `planning/adr-0016-verification-39e2cdf.md`. @@ -70,7 +70,7 @@ - Craft and clean-context did not run because adversarial blocked advancement. - Jim then directed a scope reset: ADR-0016 should state only the durable rule that public documentation covers stable software the public can obtain. Skill ownership, journey models, route truth tables, comparison algorithms, and implementation mechanics moved out of the ADR. - Concise content commit `afdaa07` replaced the detailed proposal; `f326e0c` tightened it to 477 words including metadata and headings. It now supersedes only the public source-selection/provenance clauses in ADR-0003, ADR-0004, and ADR-0006 and explicitly leaves any separate developer skill out of scope. -- Exact-head ADR Governance, 20 local governance tests, diff check, and draft-PR CI passed for `f326e0c`. The earlier route-continuity and ADR-0011 findings applied to removed decisions and require fresh review rather than mechanical remediation. +- ADR Governance, 20 local governance tests, diff check, and PR CI passed for `f326e0c`. The earlier route-continuity and ADR-0011 findings applied to removed decisions and require fresh review rather than mechanical remediation. - Fresh code review at `752099a`: passed with no findings. The 477-word ADR, template, American English, partial supersession, target-architecture scope, Accepted-ADR immutability, and exact-head CI all passed. Report: `planning/adr-0016-code-review-752099a.md`. - Goal verification at `85fde83`: ADR content passed all 11 applicable decision goals; the twelfth state/PR accuracy goal found two bookkeeping gaps. Report: `planning/adr-0016-verification-85fde83.md`. - `STATE.md` still described removed skill/mode intent. @@ -100,9 +100,15 @@ - Sweep SHA reachability run `33245584906`, job `99082354330`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. - GitBook status `GitBook`: passed. - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. -- These results are historical pre-remediation evidence. New remediation commits require fresh exact-head CI. -- Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. This correction removes those commands; fresh re-review and exact-head CI remain pending. -- Re-review of `6e9f056` found a MEDIUM CI-scope record issue and a LOW clean-context waiver-date record issue. This correction records the three scope-gated jobs as successful no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; fresh review and exact-head CI remain pending. +- These results are historical pre-remediation evidence. Subsequent remediation commits therefore required fresh current-head CI. +- Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. Commit `6e9f056` removed those commands; re-review and current-head CI were pending at that point and are completed below. +- Re-review of `6e9f056` found a MEDIUM CI-scope record issue and a LOW clean-context waiver-date record issue. Commit `1091016` records the three scope-gated jobs as successful no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; final review and CI evidence follow below. +- Final code review of remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` against base `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: passed with no findings. Report: `planning/adr-0016-evidence-remediation-code-review-1091016.md`. +- Independent verification of the same range: passed 10/10 goals. It confirmed all 31 ant-sdk refs use exact 40-character SHAs, representative URLs return HTTP 200, local-only docs commits remain unavailable and unlinked, no unreachable compare command remains, PR/base/merge and CI-scope records are accurate, Craft and waiver records are coherent, no readiness is overclaimed, the ADR tree is unchanged, and only the three in-scope planning files changed. ADR governance passed with 1 ADR checked, all 20 governance tests passed, and the diff check passed. Report: `planning/adr-0016-evidence-remediation-verification-1091016.md`. +- CI associated with reviewed remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` is green. ADR Governance run `33376786646`, job `99439965340`, was associated with that PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran. Prose run `33376786657` / job `99439965599`, sweep run `33376786692` / job `99439965589`, and sweep SHA reachability run `33376786655` / job `99439965598` were successful `not applicable` scope-gate no-ops with main validation skipped. Both GitBook statuses passed. +- Adversarial review of the remediation range: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. LOW: living state/checkpoint status lagged the PR's ready/non-draft status. NIT: `exact-head CI` wording needed to disclose execution on a clean synthetic merge ref. This record update resolves the living-status and CI-wording findings; the PR body will be reconciled after final CI. Model-diversity evidence is weaker because the reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass, and the implementer provider is unrecorded. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. +- Fresh-context Craft Review of the remediation range: PASS with no CONFORMANCE, SIMPLICITY, or NIT findings. It used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. +- Review backlog: none once required checks attached to the current PR head are green. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. - 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 @@ -114,5 +120,5 @@ ## Next -- Complete review and fresh exact-head CI for the evidence remediation. -- If those gates pass, present Proposed ADR-0016 to Jim for explicit acceptance or rejection. ADR acceptance, merge, and implementation remain unauthorized. +- Confirm required checks attached to the current PR head are green, then reconcile the PR body. +- Present Proposed ADR-0016 to Jim for explicit acceptance or rejection. Acceptance, merge, and implementation remain unauthorized. diff --git a/planning/adr-0016-evidence-remediation-adversarial-1091016.md b/planning/adr-0016-evidence-remediation-adversarial-1091016.md new file mode 100644 index 0000000..04e3883 --- /dev/null +++ b/planning/adr-0016-evidence-remediation-adversarial-1091016.md @@ -0,0 +1,35 @@ +# ADR-0016 evidence-remediation adversarial review — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `READY-WITH-NITS` + +## Scope + +Adversarial review of the planning-only evidence-remediation range and its readiness record for the Proposed ADR-0016 acceptance decision. + +## Findings + +No CRITICAL, HIGH, or MEDIUM findings. + +### LOW — Living status lagged readiness + +`planning/STATE.md` and `planning/gsd-adr-0016-checkpoint.md` still described review and CI as pending while the PR body described the proposal as ready and non-draft. + +Disposition: this final branch-local record update makes presentation conditional on required checks attached to the current PR head being green. The orchestrator will reconcile the PR body after final CI. + +### NIT — CI execution ref needed explicit wording + +The phrase `exact-head CI` did not disclose that GitHub associated ADR Governance with the PR head but executed it on a clean synthetic PR merge ref. + +Disposition: the final state and checkpoint distinguish head association from execution on the synthetic merge ref. + +## Decision boundary + +ADR-0016 can be presented for human acceptance after the current-head conditions pass. This review does not authorize acceptance, merge, implementation, or publication. + +## Independence + +Model-diversity evidence is weaker: this review used OpenAI GPT-5.6-sol, the same model as the earlier pass. The implementer provider is unrecorded, so cross-provider independence cannot be confirmed. diff --git a/planning/adr-0016-evidence-remediation-code-review-1091016.md b/planning/adr-0016-evidence-remediation-code-review-1091016.md new file mode 100644 index 0000000..266fdb5 --- /dev/null +++ b/planning/adr-0016-evidence-remediation-code-review-1091016.md @@ -0,0 +1,14 @@ +# ADR-0016 evidence-remediation code review — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Result: `passed` + +## Scope + +Final code review of the planning-only evidence-remediation range between the reviewed base and head. + +## Findings + +None. No additional code-review detail was recorded. diff --git a/planning/adr-0016-evidence-remediation-craft-1091016.md b/planning/adr-0016-evidence-remediation-craft-1091016.md new file mode 100644 index 0000000..e871953 --- /dev/null +++ b/planning/adr-0016-evidence-remediation-craft-1091016.md @@ -0,0 +1,21 @@ +# ADR-0016 evidence-remediation Craft Review — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Reviewer: Craft — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `PASS` + +## Scope + +Fresh-context Craft Review of the planning-only evidence-remediation range. + +## Findings + +- CONFORMANCE: none. +- SIMPLICITY: none. +- NIT: none. + +## Independence + +The review used fresh context but the same OpenAI GPT-5.6-sol model and provider as the earlier pass. The implementer provider is unrecorded, so independence evidence is weaker. diff --git a/planning/adr-0016-evidence-remediation-verification-1091016.md b/planning/adr-0016-evidence-remediation-verification-1091016.md new file mode 100644 index 0000000..3846ebb --- /dev/null +++ b/planning/adr-0016-evidence-remediation-verification-1091016.md @@ -0,0 +1,26 @@ +# ADR-0016 evidence-remediation verification — 1091016 + +- Date: 2026-08-31 +- Reviewed head: `109101669908e7c7d86b3dc586a9b5b17933d2d6` +- Reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` +- Reviewer: verifier +- Result: `passed` +- Score: 10/10 goals verified + +## Scope + +Independent verification of the planning-only evidence remediation in `planning/STATE.md`, `planning/gsd-adr-0016-checkpoint.md`, and `planning/released-antd-v0.11.2-audit.md`. + +## Evidence + +- All 31 ant-sdk source references use exact 40-character commit SHAs; representative blob URLs returned HTTP 200. +- Local-only documentation commits remain unavailable remotely and are not linked. +- No unreachable compare command remains. +- PR, base, merge, CI-scope, Craft Review, and clean-context-waiver records are accurate and coherent. +- The records make no readiness overclaim. +- The ADR tree is unchanged, and only the three in-scope planning files changed in the reviewed range. +- ADR governance passed with 1 ADR checked; all 20 governance tests passed; the diff check passed. + +## Findings + +None. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index bb4f8e5..dcf297b 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -1,6 +1,6 @@ # GSD Checkpoint — Concise Proposed ADR-0016 -Date: 2026-08-29 +Date: 2026-08-31 Project: Autonomi Developer Documentation Slice/question: Should public documentation describe only stable software the public can obtain? Prepared by: orchestrator @@ -8,11 +8,11 @@ Agents/tools used: operative, codereviewer, verifier, adversarial, Craft (passed ## Status -Revise — ADR substance passed, but its evidence remediation remains under review until fresh review and exact-head CI pass. +Stop for decision — present only after required checks attached to the current PR head are green. Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. -Review cadence: per-unit -Unreviewed backlog: this evidence remediation requires fresh review and exact-head CI; clean-context is explicitly Jim-waived for ADR-0016 +Review cadence: per-unit completed +Unreviewed backlog: none once current-head required checks are green; clean-context is explicitly Jim-waived for ADR-0016 ## What happened @@ -28,14 +28,14 @@ CI arbiter / green of record: - Location: PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) - Rule: required checks on the current PR head are the green of record. -- Historical pre-remediation head: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`. -- ADR Governance run `33245584910`, job `99082354387`: passed substantively; checkout, regression tests, and governance checks ran successfully. -- Prose run `33245584905`, job `99082354434`: successful scope-gate no-op (`not applicable`); checkout, setup, and the main prose validation were skipped. -- Sweep run `33245584892`, job `99082354463`: successful scope-gate no-op (`not applicable`); checkout, setup, and the main metadata-envelope validation were skipped. -- Sweep SHA reachability run `33245584906`, job `99082354330`: successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. +- Reviewed remediation head: `109101669908e7c7d86b3dc586a9b5b17933d2d6`; reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`. +- ADR Governance run `33376786646`, job `99439965340`: associated with the reviewed PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran successfully. +- Prose run `33376786657`, job `99439965599`: successful scope-gate no-op (`not applicable`); main validation was skipped. +- Sweep run `33376786692`, job `99439965589`: successful scope-gate no-op (`not applicable`); main validation was skipped. +- Sweep SHA reachability run `33376786655`, job `99439965598`: successful scope-gate no-op (`not applicable`); main validation was skipped. - GitBook status `GitBook`: passed. - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. -- These checks are historical pre-remediation evidence. The evidence-repair commit requires fresh exact-head CI. +- Current PR required checks are the green of record. The final checkpoint-only commit must receive the same green current-head checks before presentation. Local fast gate / `.gsd/gate.sh`: @@ -58,8 +58,8 @@ Artifacts: - No-harness-modification: Pass. No gate, CI, test, build, or environment change. - Baseline-diff for evidence: Pass. No failure was dismissed. -- Evidence reproducible-from-branch: Pending. This correction removes the known unreachable commands; fresh re-review remains pending. -- Local vs CI consistency: Pending. Pre-remediation checks passed; the evidence-repair commit requires fresh exact-head CI. +- Evidence reproducible-from-branch: Pass. +- Local vs CI consistency: Pass for the reviewed remediation. Presentation is conditioned on final current-head green. ## Review Findings @@ -69,25 +69,29 @@ Code review: - Focused evidence-wording review at `fc49173`: ADR passed; the old checkpoint had one MEDIUM consistency finding. - Disposition: replaced the old accumulated checkpoint with this concise current record. - Focused review of the replacement checkpoint at `dcf7c8c`: passed with no findings. -- Attended code review of `7b8b537`: HIGH evidence-reproducibility finding; two GitHub compare calls in the audit targeted local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93` and failed remotely. This correction removes the unreachable commands; fresh re-review and exact-head CI remain pending. -- Re-review of `6e9f056`: MEDIUM CI-scope record issue and LOW clean-context waiver-date record issue. This correction records prose, sweep, and sweep SHA reachability as successful scope-gate no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; fresh review and exact-head CI remain pending. +- Attended code review of `7b8b537`: HIGH evidence-reproducibility finding; two GitHub compare calls in the audit targeted local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93` and failed remotely. Commit `6e9f056` removed those commands; re-review and current-head CI were pending at that point and are completed below. +- Re-review of `6e9f056`: MEDIUM CI-scope record issue and LOW clean-context waiver-date record issue. Commit `1091016` records prose, sweep, and sweep SHA reachability as successful scope-gate no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; final review and CI evidence follow below. +- Final review of remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` against base `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: passed with no findings. Report: `planning/adr-0016-evidence-remediation-code-review-1091016.md`. Goal verification: - Final concise verification at `58545cd`: passed 12/12 with no gaps. - Later ADR change: one validation line aligned with an already-authorized evidence path; focused code review passed it. +- Final remediation verification: passed 10/10 goals. It confirmed exact 40-character ant-sdk refs, reachable representative URLs, unlinked local-only docs commits, removal of unreachable compare commands, accurate PR/base/merge and CI-scope records, coherent Craft/waiver records, no readiness overclaim, an unchanged ADR tree, and only three in-scope planning-file changes. Report: `planning/adr-0016-evidence-remediation-verification-1091016.md`. Adversarial review: - Review at `d18a63b`: READY-WITH-NITS; no CRITICAL, HIGH, or MEDIUM findings. - Deployed-network validation wording nit: corrected in `dfe2161` and passed focused review. - Stale PR-body nit: corrected. +- Final remediation review: `READY-WITH-NITS`; no CRITICAL, HIGH, or MEDIUM findings. LOW: living state/checkpoint status lagged the ready, non-draft PR. NIT: `exact-head CI` wording needed to distinguish PR-head association from synthetic-merge-ref execution. This record update resolves the living-status and CI-wording findings; the orchestrator will reconcile the PR body after final CI. The reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass; the implementer provider is unrecorded, so model-independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. Craft Review: - Required: Yes. - Result: Pass at `dcf7c8c`; no CONFORMANCE, SIMPLICITY, or NIT findings. - Report: `planning/adr-0016-craft-dcf7c8c.md`. +- Final remediation result: PASS in fresh context; no CONFORMANCE, SIMPLICITY, or NIT findings. The reviewer used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. Clean-context review: @@ -108,18 +112,18 @@ Merge commit `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` integrated current base ## Open Questions / Decisions for Jim -The acceptance decision waits for the evidence remediation's fresh review and exact-head CI. The clean-context waiver does not itself accept the ADR or authorize merge or implementation. +The acceptance decision waits only for required checks attached to the final current PR head and PR-body reconciliation. The clean-context waiver does not itself accept the ADR or authorize merge or implementation. PR / upstream action gate: - PR status: already open and non-draft. -- Merge ready? No; the evidence remediation requires fresh review and exact-head CI. +- Merge ready? No; merge remains unauthorized. - Jim authorized merge? No. ## Recommended Next Step -Rerun checks, review, and exact-head CI for this evidence repair, then present Proposed ADR-0016 for the acceptance decision. Acceptance, merge, and implementation remain separate unauthorized actions. +After required checks attached to the current PR head are green and the PR body is reconciled, Jim accepts or rejects Proposed ADR-0016. Do not accept, merge, or implement it. ## Handoff Note -The concise ADR's substance passed code review, goal verification, adversarial review, and Craft Review. Clean-context is explicitly waived for ADR-0016. The evidence repair now requires fresh review and exact-head CI before the acceptance decision; ADR-0016 remains Proposed, and acceptance, merge, and implementation remain unauthorized. +The concise ADR and evidence remediation passed final code review, goal verification, adversarial review, and Craft Review. Clean-context is explicitly Jim-waived for ADR-0016. Presentation is conditioned on green required checks attached to the final current PR head and PR-body reconciliation. ADR-0016 remains Proposed; acceptance, merge, implementation, and publication remain unauthorized. From b0d01f41cc1a688699a3614ab4f3243362542a4f Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 31 Aug 2026 10:59:39 +0100 Subject: [PATCH 47/50] docs(adr-0016): correct adversarial transcription - Record stale draft language in the PR body - Preserve live non-draft PR status --- planning/STATE.md | 2 +- planning/adr-0016-evidence-remediation-adversarial-1091016.md | 4 ++-- planning/gsd-adr-0016-checkpoint.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/planning/STATE.md b/planning/STATE.md index d6653c9..af6115b 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -106,7 +106,7 @@ - Final code review of remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` against base `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: passed with no findings. Report: `planning/adr-0016-evidence-remediation-code-review-1091016.md`. - Independent verification of the same range: passed 10/10 goals. It confirmed all 31 ant-sdk refs use exact 40-character SHAs, representative URLs return HTTP 200, local-only docs commits remain unavailable and unlinked, no unreachable compare command remains, PR/base/merge and CI-scope records are accurate, Craft and waiver records are coherent, no readiness is overclaimed, the ADR tree is unchanged, and only the three in-scope planning files changed. ADR governance passed with 1 ADR checked, all 20 governance tests passed, and the diff check passed. Report: `planning/adr-0016-evidence-remediation-verification-1091016.md`. - CI associated with reviewed remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` is green. ADR Governance run `33376786646`, job `99439965340`, was associated with that PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran. Prose run `33376786657` / job `99439965599`, sweep run `33376786692` / job `99439965589`, and sweep SHA reachability run `33376786655` / job `99439965598` were successful `not applicable` scope-gate no-ops with main validation skipped. Both GitBook statuses passed. -- Adversarial review of the remediation range: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. LOW: living state/checkpoint status lagged the PR's ready/non-draft status. NIT: `exact-head CI` wording needed to disclose execution on a clean synthetic merge ref. This record update resolves the living-status and CI-wording findings; the PR body will be reconciled after final CI. Model-diversity evidence is weaker because the reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass, and the implementer provider is unrecorded. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. +- Adversarial review of the remediation range: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. LOW: living records lagged completed review and CI; the PR body claimed the ADR was ready but repeatedly used stale `draft` language while live PR #98 was open and non-draft. NIT: `exact-head CI` wording needed to disclose execution on a clean synthetic merge ref. This record update resolves the living-status and CI-wording findings; the orchestrator will remove the stale `draft` wording from the PR body after final CI. Model-diversity evidence is weaker because the reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass, and the implementer provider is unrecorded. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. - Fresh-context Craft Review of the remediation range: PASS with no CONFORMANCE, SIMPLICITY, or NIT findings. It used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. - Review backlog: none once required checks attached to the current PR head are green. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. - 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. diff --git a/planning/adr-0016-evidence-remediation-adversarial-1091016.md b/planning/adr-0016-evidence-remediation-adversarial-1091016.md index 04e3883..519f531 100644 --- a/planning/adr-0016-evidence-remediation-adversarial-1091016.md +++ b/planning/adr-0016-evidence-remediation-adversarial-1091016.md @@ -16,9 +16,9 @@ No CRITICAL, HIGH, or MEDIUM findings. ### LOW — Living status lagged readiness -`planning/STATE.md` and `planning/gsd-adr-0016-checkpoint.md` still described review and CI as pending while the PR body described the proposal as ready and non-draft. +`planning/STATE.md` and `planning/gsd-adr-0016-checkpoint.md` still described review and CI as pending. The PR body claimed the ADR was ready but repeatedly used stale `draft` language, while live PR #98 was open and non-draft. -Disposition: this final branch-local record update makes presentation conditional on required checks attached to the current PR head being green. The orchestrator will reconcile the PR body after final CI. +Disposition: the final branch-local record update resolves the living-status and CI-wording findings. The orchestrator will remove the stale `draft` wording from the PR body after final CI. ### NIT — CI execution ref needed explicit wording diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index dcf297b..917fbb5 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -84,7 +84,7 @@ Adversarial review: - Review at `d18a63b`: READY-WITH-NITS; no CRITICAL, HIGH, or MEDIUM findings. - Deployed-network validation wording nit: corrected in `dfe2161` and passed focused review. - Stale PR-body nit: corrected. -- Final remediation review: `READY-WITH-NITS`; no CRITICAL, HIGH, or MEDIUM findings. LOW: living state/checkpoint status lagged the ready, non-draft PR. NIT: `exact-head CI` wording needed to distinguish PR-head association from synthetic-merge-ref execution. This record update resolves the living-status and CI-wording findings; the orchestrator will reconcile the PR body after final CI. The reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass; the implementer provider is unrecorded, so model-independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. +- Final remediation review: `READY-WITH-NITS`; no CRITICAL, HIGH, or MEDIUM findings. LOW: living records lagged completed review and CI; the PR body claimed the ADR was ready but repeatedly used stale `draft` language while live PR #98 was open and non-draft. NIT: `exact-head CI` wording needed to distinguish PR-head association from synthetic-merge-ref execution. This record update resolves the living-status and CI-wording findings; the orchestrator will remove the stale `draft` wording from the PR body after final CI. The reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass; the implementer provider is unrecorded, so model-independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. Craft Review: From fc1102b2c6f87e0557553f567a5fc60728b2d0af Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:12:25 +0100 Subject: [PATCH 48/50] docs(adr-0016): record human acceptance - Mark ADR-0016 Accepted after Jim's review of PR #98 - Record merge authorization and preserve the implementation gate --- ...eleased-truth-for-public-developer-docs.md | 6 ++-- planning/STATE.md | 20 ++++++------ planning/gsd-adr-0016-checkpoint.md | 32 ++++++++++--------- 3 files changed, 31 insertions(+), 27 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 038f09c..22fad99 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -1,7 +1,7 @@ # ADR-0016: Public documentation describes obtainable releases -- **Status:** Proposed -- **Acceptance:** Prospective; pending Jim Collinson's human review and acceptance +- **Status:** Accepted +- **Acceptance:** Prospective — accepted by Jim Collinson as decision owner after review of PR #98 on 2026-08-31. - **Date:** 2026-08-12 - **Decision owners:** Jim Collinson - **Reviewers:** Jim Collinson @@ -75,4 +75,4 @@ Implementation details and sequencing belong in a reviewed specification and pla ## Notes for AI-assisted work -AI may draft but not accept this ADR. Acceptance requires human review. Later decision changes require a superseding ADR. +AI tools helped draft this ADR. Jim Collinson accepted it after human review of PR #98 on 2026-08-31. The introducing PR remains reviewable until merge; once this Accepted record lands on the default branch, future changes require a superseding ADR. diff --git a/planning/STATE.md b/planning/STATE.md index af6115b..1ce27c1 100644 --- a/planning/STATE.md +++ b/planning/STATE.md @@ -4,15 +4,16 @@ - Phase: released-truth source-of-truth decision - Plan: supersede ADR-0003 before documentation remediation -- Task: human acceptance decision for Proposed ADR-0016 after final current-PR-head checks -- Status: acceptance-ready when required checks attached to the current PR head are green; clean-context is explicitly waived for this ADR +- Task: record Jim Collinson's 2026-08-31 acceptance of ADR-0016 and authorization to merge PR #98 +- Status: ADR-0016 was accepted by Jim on 2026-08-31; PR #98 merge is explicitly authorized after final validation and required current-head CI are green - Mode: attended - Branch: `adr/released-and-usable-truth` - PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) - Branch point: `af6d0e9da96dd9b7d31105accbeb9b6a181aaf37` - Current PR base: `origin/main` at `49e202c818bab1be780b81c28e5d0718cfb89b1c` - Current concise ADR content: redraft `afdaa07ec909475f69fff16229952559b1e415ee`; tightening `f326e0c3f65de0646495da02d6eb74b70dac966f`; evidence-alignment correction `dfe2161` -- Implementation: not started; ADR acceptance remains human-only +- Implementation: not started or authorized; it requires a separate approved spec, plan, and slice plus a fresh release audit +- Human decision supplied in chat on 2026-08-31: Jim is happy to accept ADR-0016 via PR #98 and authorizes it to be accepted and merged. Writing `Accepted` records and implements Jim's decision; it is not autonomous AI acceptance. ## Decision Intent @@ -108,17 +109,18 @@ - CI associated with reviewed remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` is green. ADR Governance run `33376786646`, job `99439965340`, was associated with that PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran. Prose run `33376786657` / job `99439965599`, sweep run `33376786692` / job `99439965589`, and sweep SHA reachability run `33376786655` / job `99439965598` were successful `not applicable` scope-gate no-ops with main validation skipped. Both GitBook statuses passed. - Adversarial review of the remediation range: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. LOW: living records lagged completed review and CI; the PR body claimed the ADR was ready but repeatedly used stale `draft` language while live PR #98 was open and non-draft. NIT: `exact-head CI` wording needed to disclose execution on a clean synthetic merge ref. This record update resolves the living-status and CI-wording findings; the orchestrator will remove the stale `draft` wording from the PR body after final CI. Model-diversity evidence is weaker because the reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass, and the implementer provider is unrecorded. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. - Fresh-context Craft Review of the remediation range: PASS with no CONFORMANCE, SIMPLICITY, or NIT findings. It used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. -- Review backlog: none once required checks attached to the current PR head are green. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. +- Review backlog: prior proposal review is complete. Independent review, verification, and gauntlet checks for the acceptance record plus required checks on the final PR head remain before merge. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. - Freshness risk: the imported v0.11.2 audit is explicitly historical; `antd` v0.12.0 has since released and issue #233 has closed. A fresh candidate-release audit is required before implementation, regardless of ADR acceptance. ## Constraints - Do not edit Accepted ADR-0003 or ADR-0004. -- Do not mark ADR-0016 Accepted autonomously. -- Do not implement manifest, tooling, policy, or rendered-documentation changes before the ADR decision gate. -- Do not merge PR #98 without Jim's explicit confirmation. +- The `Accepted` status implements Jim's explicit 2026-08-31 decision; it is not autonomous AI acceptance. +- Do not implement manifest, tooling, policy, or rendered-documentation changes without a separate approved spec, plan, and slice plus a fresh release audit. +- Jim authorized merge of PR #98 on 2026-08-31, conditional on final validation and required current-head CI being green. ## Next -- Confirm required checks attached to the current PR head are green, then reconcile the PR body. -- Present Proposed ADR-0016 to Jim for explicit acceptance or rejection. Acceptance, merge, and implementation remain unauthorized. +- Run local validation and independent acceptance-record review, verification, and gauntlet checks. +- Confirm required checks attached to the final PR head are green, then merge PR #98 under Jim's authorization. +- Do not begin implementation. After merge, ADR-0016 is immutable; later changes require a superseding ADR. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 917fbb5..484156f 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -1,4 +1,4 @@ -# GSD Checkpoint — Concise Proposed ADR-0016 +# GSD Checkpoint — Accepted ADR-0016 Date: 2026-08-31 Project: Autonomi Developer Documentation @@ -8,19 +8,21 @@ Agents/tools used: operative, codereviewer, verifier, adversarial, Craft (passed ## Status -Stop for decision — present only after required checks attached to the current PR head are green. +Continue — Jim accepted ADR-0016 and authorized merge of PR #98 on 2026-08-31; complete final mechanical validation and final-head CI, then merge under that authorization. -Meaningful work-unit? Yes — the proposal changes the durable public source-of-truth policy. -Review cadence: per-unit completed -Unreviewed backlog: none once current-head required checks are green; clean-context is explicitly Jim-waived for ADR-0016 +Meaningful work-unit? Yes — the decision changes the durable public source-of-truth policy. +Review cadence: prior per-unit reviews completed; independent acceptance-record review, verification, and gauntlet checks precede merge +Unreviewed backlog: the acceptance-record update and final PR head; clean-context remains explicitly Jim-waived for ADR-0016 ## What happened Jim replaced the detailed proposal with a concise target decision: public documentation describes stable or general-availability software available through supported public routes. An explicit release baseline provides exact provenance; unreleased source cannot support default public claims; defects and unsupported tasks are represented honestly. -The ADR is 481 words including metadata and headings. Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside its scope. It partially supersedes only ADR-0003, ADR-0004, and ADR-0006. +The ADR is 510 words including metadata and headings. Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside its scope. It partially supersedes only ADR-0003, ADR-0004, and ADR-0006. -ADR-0016 remains Proposed. No implementation, rendered docs, skill, CI, test, or Accepted ADR changed. +Jim's explicit human decision, supplied in chat on 2026-08-31, is to accept ADR-0016 via PR #98 and authorize it to be accepted and merged. Writing `Accepted` implements Jim's decision; it is not autonomous AI acceptance. + +No implementation, rendered docs, skill, CI, test, harness, or other ADR changed. Implementation remains unauthorized without a separate approved spec, plan, and slice plus a fresh release audit. The introducing PR remains reviewable until merge; after ADR-0016 lands on the default branch, it is immutable and later changes require a superseding ADR. ## Evidence @@ -35,7 +37,7 @@ CI arbiter / green of record: - Sweep SHA reachability run `33376786655`, job `99439965598`: successful scope-gate no-op (`not applicable`); main validation was skipped. - GitBook status `GitBook`: passed. - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. -- Current PR required checks are the green of record. The final checkpoint-only commit must receive the same green current-head checks before presentation. +- Current PR required checks are the green of record. The final acceptance-record commit must receive green current-head checks before merge. Local fast gate / `.gsd/gate.sh`: @@ -44,7 +46,7 @@ Local fast gate / `.gsd/gate.sh`: - Governance tests: passed, 20 tests. - ant-sdk blob ref length check: passed, 31 refs checked and all are 40 characters. - `git diff --check`: passed. -- Word count: 481. +- Word count: 510. Artifacts: @@ -59,7 +61,7 @@ Artifacts: - No-harness-modification: Pass. No gate, CI, test, build, or environment change. - Baseline-diff for evidence: Pass. No failure was dismissed. - Evidence reproducible-from-branch: Pass. -- Local vs CI consistency: Pass for the reviewed remediation. Presentation is conditioned on final current-head green. +- Local vs CI consistency: Pass for the reviewed remediation. Merge is conditioned on final current-head green. ## Review Findings @@ -112,18 +114,18 @@ Merge commit `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` integrated current base ## Open Questions / Decisions for Jim -The acceptance decision waits only for required checks attached to the final current PR head and PR-body reconciliation. The clean-context waiver does not itself accept the ADR or authorize merge or implementation. +No further acceptance or merge decision is pending. Jim accepted ADR-0016 and authorized merge of PR #98 on 2026-08-31. Final validation and required checks on the final PR head remain mechanical pre-merge conditions. This authorization does not authorize implementation. PR / upstream action gate: - PR status: already open and non-draft. -- Merge ready? No; merge remains unauthorized. -- Jim authorized merge? No. +- Merge ready? Conditional on final validation and required final-head CI being green. +- Jim authorized merge? Yes — on 2026-08-31. ## Recommended Next Step -After required checks attached to the current PR head are green and the PR body is reconciled, Jim accepts or rejects Proposed ADR-0016. Do not accept, merge, or implement it. +Run local validation, independent acceptance-record review, verification, and gauntlet checks, then obtain green required checks on the final PR head and merge PR #98 under Jim's authorization. Do not begin implementation. ## Handoff Note -The concise ADR and evidence remediation passed final code review, goal verification, adversarial review, and Craft Review. Clean-context is explicitly Jim-waived for ADR-0016. Presentation is conditioned on green required checks attached to the final current PR head and PR-body reconciliation. ADR-0016 remains Proposed; acceptance, merge, implementation, and publication remain unauthorized. +The concise ADR and evidence remediation passed final code review, goal verification, adversarial review, and Craft Review. Clean-context remains explicitly Jim-waived for ADR-0016. Jim accepted ADR-0016 and authorized merge of PR #98 on 2026-08-31. Complete acceptance-record review and verification, final-head CI, and merge; do not begin implementation. Once merged, ADR-0016 is immutable and later changes require a superseding ADR. From e2d54b26e5d510419885345e22a2374d46aeb710 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:17:46 +0100 Subject: [PATCH 49/50] docs(adr-0016): restore approved word limit - Shorten the accepted-record AI note without changing acceptance metadata - Record the verified 497-word full-file count --- adr/ADR-0016-released-truth-for-public-developer-docs.md | 2 +- planning/gsd-adr-0016-checkpoint.md | 4 ++-- 2 files changed, 3 insertions(+), 3 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 22fad99..ea1bea7 100644 --- a/adr/ADR-0016-released-truth-for-public-developer-docs.md +++ b/adr/ADR-0016-released-truth-for-public-developer-docs.md @@ -75,4 +75,4 @@ Implementation details and sequencing belong in a reviewed specification and pla ## Notes for AI-assisted work -AI tools helped draft this ADR. Jim Collinson accepted it after human review of PR #98 on 2026-08-31. The introducing PR remains reviewable until merge; once this Accepted record lands on the default branch, future changes require a superseding ADR. +AI tools helped draft this ADR. Jim Collinson accepted it through PR #98 on 2026-08-31. The PR remains reviewable until merge; later changes require a superseding ADR. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 484156f..811e21f 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -18,7 +18,7 @@ Unreviewed backlog: the acceptance-record update and final PR head; clean-contex Jim replaced the detailed proposal with a concise target decision: public documentation describes stable or general-availability software available through supported public routes. An explicit release baseline provides exact provenance; unreleased source cannot support default public claims; defects and unsupported tasks are represented honestly. -The ADR is 510 words including metadata and headings. Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside its scope. It partially supersedes only ADR-0003, ADR-0004, and ADR-0006. +The ADR is 497 words including metadata and headings. Skill ownership, journey models, route truth tables, release comparison, manifest schemas, and implementation mechanics are outside its scope. It partially supersedes only ADR-0003, ADR-0004, and ADR-0006. Jim's explicit human decision, supplied in chat on 2026-08-31, is to accept ADR-0016 via PR #98 and authorize it to be accepted and merged. Writing `Accepted` implements Jim's decision; it is not autonomous AI acceptance. @@ -46,7 +46,7 @@ Local fast gate / `.gsd/gate.sh`: - Governance tests: passed, 20 tests. - ant-sdk blob ref length check: passed, 31 refs checked and all are 40 characters. - `git diff --check`: passed. -- Word count: 510. +- Word count: 497. Artifacts: From 789b8c672792464ea380626f745807902e443d10 Mon Sep 17 00:00:00 2001 From: Jim Collinson <13061030+JimCollinson@users.noreply.github.com> Date: Mon, 31 Aug 2026 14:04:58 +0100 Subject: [PATCH 50/50] docs(adr-0016): reconcile acceptance evidence - Add branch-local acceptance review reports - Record exact CI roles and remaining mechanical gates --- planning/STATE.md | 41 ++++++---- ...adr-0016-acceptance-adversarial-e2d54b2.md | 38 +++++++++ ...adr-0016-acceptance-code-review-e2d54b2.md | 19 +++++ ...dr-0016-acceptance-verification-e2d54b2.md | 26 ++++++ planning/gsd-adr-0016-checkpoint.md | 80 +++++++++++-------- 5 files changed, 156 insertions(+), 48 deletions(-) create mode 100644 planning/adr-0016-acceptance-adversarial-e2d54b2.md create mode 100644 planning/adr-0016-acceptance-code-review-e2d54b2.md create mode 100644 planning/adr-0016-acceptance-verification-e2d54b2.md diff --git a/planning/STATE.md b/planning/STATE.md index 1ce27c1..856c1c7 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: record Jim Collinson's 2026-08-31 acceptance of ADR-0016 and authorization to merge PR #98 -- Status: ADR-0016 was accepted by Jim on 2026-08-31; PR #98 merge is explicitly authorized after final validation and required current-head CI are green +- Task: reconcile final acceptance-record evidence after exact-head adversarial review +- Status: ADR-0016 is Accepted by Jim; merge authorization is settled; implementation remains unauthorized; final adversarial rerun, Craft Review, any needed focused consistency check, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head remain as mechanical merge conditions - Mode: attended - Branch: `adr/released-and-usable-truth` - PR: https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) @@ -94,22 +94,35 @@ - Jim explicitly authorized creation of disposable root `gsd-panel-a1ae9d0a-d513-47f5-8266-b006db956517` and a credential-free brief of at most 16 KiB for revision `0df9bfd`. The outer harness still denied the exact `mkdir` call because its final static external-directory deny overrides the authorization. This is now a mechanism-level blocker; no model ran. - Jim's `waive and present` declaration was recorded in commit `f3f3bdc735d5357ea4a03741163a800510a8b61c` on 2026-08-29. This is a one-off explicit waiver of the ADR-0016 clean-context gate after the controlled panel failed before inference. It does not waive clean-context generally or change panel policy. - Clean-context controlling disposition: Jim's one-off waiver follows the blocked-before-inference controlled-panel sequence above; no same-model substitute ran. -- CI arbiter: required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: - - ADR Governance run `33245584910`, job `99082354387`, passed substantively; checkout, regression tests, and governance checks ran successfully. - - Prose run `33245584905`, job `99082354434`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main prose validation were skipped. - - Sweep run `33245584892`, job `99082354463`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main metadata-envelope validation were skipped. - - Sweep SHA reachability run `33245584906`, job `99082354330`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. +- CI arbiter: process-required ADR Governance and the GitHub branch-protection-required checks on the current PR #98 head are the green of record. At pre-remediation head `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: + - Process-required ADR Governance run `33245584910`, job `99082354387`, passed substantively; checkout, regression tests, and governance checks ran successfully. + - GitHub branch-protection-required prose run `33245584905`, job `99082354434`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main prose validation were skipped. + - GitHub branch-protection-required sweep run `33245584892`, job `99082354463`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main metadata-envelope validation were skipped. + - GitHub branch-protection-required sweep SHA reachability run `33245584906`, job `99082354330`, was a successful scope-gate no-op (`not applicable`); checkout, setup, and the main reachability validation were skipped. - GitBook status `GitBook`: passed. - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. -- These results are historical pre-remediation evidence. Subsequent remediation commits therefore required fresh current-head CI. -- Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. Commit `6e9f056` removed those commands; re-review and current-head CI were pending at that point and are completed below. +- These results are historical pre-remediation evidence. Subsequent remediation commits therefore required fresh process-required ADR Governance and GitHub branch-protection-required checks. +- Attended code review of `7b8b537` found a HIGH evidence-reproducibility issue: the audit's reproducible command block included two GitHub compare calls ending at local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93`, which is unreachable remotely. Commit `6e9f056` removed those commands; re-review and fresh process-required ADR Governance plus GitHub branch-protection-required checks were pending at that point and are completed below. - Re-review of `6e9f056` found a MEDIUM CI-scope record issue and a LOW clean-context waiver-date record issue. Commit `1091016` records the three scope-gated jobs as successful no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; final review and CI evidence follow below. - Final code review of remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` against base `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: passed with no findings. Report: `planning/adr-0016-evidence-remediation-code-review-1091016.md`. - Independent verification of the same range: passed 10/10 goals. It confirmed all 31 ant-sdk refs use exact 40-character SHAs, representative URLs return HTTP 200, local-only docs commits remain unavailable and unlinked, no unreachable compare command remains, PR/base/merge and CI-scope records are accurate, Craft and waiver records are coherent, no readiness is overclaimed, the ADR tree is unchanged, and only the three in-scope planning files changed. ADR governance passed with 1 ADR checked, all 20 governance tests passed, and the diff check passed. Report: `planning/adr-0016-evidence-remediation-verification-1091016.md`. -- CI associated with reviewed remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` is green. ADR Governance run `33376786646`, job `99439965340`, was associated with that PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran. Prose run `33376786657` / job `99439965599`, sweep run `33376786692` / job `99439965589`, and sweep SHA reachability run `33376786655` / job `99439965598` were successful `not applicable` scope-gate no-ops with main validation skipped. Both GitBook statuses passed. +- CI associated with reviewed remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` is green. Process-required ADR Governance run `33376786646`, job `99439965340`, was associated with that PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran. GitHub branch-protection-required prose run `33376786657` / job `99439965599`, sweep run `33376786692` / job `99439965589`, and sweep SHA reachability run `33376786655` / job `99439965598` were successful `not applicable` scope-gate no-ops with main validation skipped. Both GitBook statuses passed. - Adversarial review of the remediation range: `READY-WITH-NITS`, with no CRITICAL, HIGH, or MEDIUM findings. LOW: living records lagged completed review and CI; the PR body claimed the ADR was ready but repeatedly used stale `draft` language while live PR #98 was open and non-draft. NIT: `exact-head CI` wording needed to disclose execution on a clean synthetic merge ref. This record update resolves the living-status and CI-wording findings; the orchestrator will remove the stale `draft` wording from the PR body after final CI. Model-diversity evidence is weaker because the reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass, and the implementer provider is unrecorded. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. - Fresh-context Craft Review of the remediation range: PASS with no CONFORMANCE, SIMPLICITY, or NIT findings. It used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. -- Review backlog: prior proposal review is complete. Independent review, verification, and gauntlet checks for the acceptance record plus required checks on the final PR head remain before merge. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. +- Acceptance-record code review of `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`: passed with no findings. ADR governance passed with 1 ADR checked, all 20 governance tests passed, and diff/protected-scope checks passed. Only the three expected files changed. ADR-0016 changed only Status, Acceptance, and the final note; its decision remained unchanged at 497 words. Acceptance, merge authorization, the final-head CI condition for process-required ADR Governance plus GitHub branch-protection-required checks, implementation prohibition, clean-context waiver, and default-branch immutability were coherent. Report: `planning/adr-0016-acceptance-code-review-e2d54b2.md`. +- Independent acceptance-record verification of the same range: passed 7/7. Jim, PR #98, and 2026-08-31 form the recorded human-acceptance basis; ADR-0015 permits the introducing-PR transition and places immutability at the default branch; only authorized scopes changed; governance, tests, and diff checks passed. At review time the remote still needed the acceptance commits; that condition has since been satisfied and CI associated with `e2d54b26e5d510419885345e22a2374d46aeb710` is green. Report: `planning/adr-0016-acceptance-verification-e2d54b2.md`. +- CI associated with accepted head `e2d54b26e5d510419885345e22a2374d46aeb710` is green: + - Process-required ADR Governance run `33392124485`, job `99487983002`, was associated with head `e2d54b2` and ran on clean synthetic merge ref `c53dfc6d1b422099ed5dadb2406f0d8876409920`; checkout, all 20 tests, and governance passed. ADR Governance is process-required but is not GitHub branch-protection-required. + - GitHub branch-protection-required prose run `33392124442`, job `99487983034`, sweep run `33392124448`, job `99487983102`, and sweep SHA reachability run `33392124434`, job `99487982641`, all passed as `not applicable` scope-gate no-ops with main validation skipped. + - Both GitBook statuses passed. +- Exact-head adversarial review at `e2d54b26e5d510419885345e22a2374d46aeb710`: `NOT-READY`. Report: `planning/adr-0016-acceptance-adversarial-e2d54b2.md`. + - HIGH: the live PR body contradicted acceptance and merge authorization and had stale head, count, and merge-ref evidence. The orchestrator corrected the live PR body before this reconciliation commit. + - MEDIUM: state and checkpoint still marked completed code review, verification, and CI pending and lacked branch-local code-review and 7/7 verification reports. This reconciliation commit updates the records and adds both reports. + - LOW: generic `required checks` wording obscured that ADR Governance is process-required but not GitHub branch-protection-required; GitHub branch protection requires only prose, sweep, and sweep SHA reachability, all `not applicable` no-ops here. This reconciliation commit uses explicit wording. + - No content or governance failure was found: the ADR decision remained unchanged at 497 words, local checks passed, and ADR-0015 alignment was correct. + - The reviewer was OpenAI GPT-5.6-sol, the same provider/model as the earlier review. The implementer provider is unrecorded, so independence evidence is weaker. +- Prior proposal Craft Review passed. Acceptance-record Craft Review has not run because the exact-head adversarial review blocked it. Final adversarial rerun and Craft Review are mandatory merge conditions after this reconciliation commit. Clean-context remains Jim-waived for ADR-0016; no substitute review ran. +- Remaining merge conditions are a final adversarial rerun, Craft Review, a focused consistency check as needed, and green process-required ADR Governance plus GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final head. These are mechanical conditions, not owner decisions. - Freshness risk: the imported v0.11.2 audit is explicitly historical; `antd` v0.12.0 has since released and issue #233 has closed. A fresh candidate-release audit is required before implementation, regardless of ADR acceptance. ## Constraints @@ -117,10 +130,10 @@ - Do not edit Accepted ADR-0003 or ADR-0004. - The `Accepted` status implements Jim's explicit 2026-08-31 decision; it is not autonomous AI acceptance. - Do not implement manifest, tooling, policy, or rendered-documentation changes without a separate approved spec, plan, and slice plus a fresh release audit. -- Jim authorized merge of PR #98 on 2026-08-31, conditional on final validation and required current-head CI being green. +- Jim authorized merge of PR #98 on 2026-08-31, conditional on final mechanical review and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head. ## Next -- Run local validation and independent acceptance-record review, verification, and gauntlet checks. -- Confirm required checks attached to the final PR head are green, then merge PR #98 under Jim's authorization. +- Run the final adversarial rerun, Craft Review, and a focused consistency check as needed. +- Confirm process-required ADR Governance and GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final PR head are green, then merge PR #98 under Jim's authorization. - Do not begin implementation. After merge, ADR-0016 is immutable; later changes require a superseding ADR. diff --git a/planning/adr-0016-acceptance-adversarial-e2d54b2.md b/planning/adr-0016-acceptance-adversarial-e2d54b2.md new file mode 100644 index 0000000..f40cd5b --- /dev/null +++ b/planning/adr-0016-acceptance-adversarial-e2d54b2.md @@ -0,0 +1,38 @@ +# ADR-0016 acceptance-record adversarial review — e2d54b2 + +- Date: 2026-08-31 +- Reviewed head: `e2d54b26e5d510419885345e22a2374d46aeb710` +- Reviewer: adversarial — OpenAI GPT-5.6-sol (`openai/gpt-5.6-sol`) +- Result: `NOT-READY` + +## Findings + +### HIGH — Live PR body contradicted acceptance and merge authorization + +The live PR body contradicted acceptance and merge authorization and had stale head, count, and merge-ref evidence. + +Disposition: the orchestrator corrected the live PR body before the evidence-reconciliation commit. + +### MEDIUM — Living records and branch-local reports lagged completed evidence + +`planning/STATE.md` and `planning/gsd-adr-0016-checkpoint.md` still marked completed code review, verification, and CI pending and lacked branch-local code-review and 7/7 verification reports. + +Disposition: the evidence-reconciliation commit updates both living records and adds the missing reports. + +### LOW — Required-check wording obscured the CI distinction + +Generic `required checks` wording obscured that ADR Governance is process-required but not GitHub branch-protection-required. GitHub branch protection requires only prose, sweep, and sweep SHA reachability, all of which were green `not applicable` scope-gate no-ops here. + +Disposition: the evidence-reconciliation commit uses explicit process-required and GitHub branch-protection-required wording. + +## Content and governance + +No content or governance failure was found. ADR-0016's decision remained unchanged, the ADR contained 497 words, local checks passed, and alignment with ADR-0015 was correct. + +## Independence + +This review used OpenAI GPT-5.6-sol, the same provider and model as the earlier review. The implementer provider is unrecorded, so independence evidence is weaker. + +## Remaining merge conditions + +Final adversarial rerun and Craft Review are mandatory after the evidence-reconciliation commit. Neither has passed yet. diff --git a/planning/adr-0016-acceptance-code-review-e2d54b2.md b/planning/adr-0016-acceptance-code-review-e2d54b2.md new file mode 100644 index 0000000..8176dd7 --- /dev/null +++ b/planning/adr-0016-acceptance-code-review-e2d54b2.md @@ -0,0 +1,19 @@ +# ADR-0016 acceptance-record code review — e2d54b2 + +- Date: 2026-08-31 +- Reviewed range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710` +- Result: `passed` + +## Checks + +- ADR governance: passed, 1 ADR checked. +- Governance tests: passed, 20/20 tests. +- Diff and protected scope: passed. +- Only the three expected files changed. +- ADR-0016 changed only Status, Acceptance, and the final note. +- ADR-0016's decision remained unchanged and the ADR contained 497 words. +- Acceptance, merge authorization, the final-head CI condition for process-required ADR Governance plus GitHub branch-protection-required checks, implementation prohibition, clean-context waiver, and default-branch immutability were coherent. + +## Findings + +None. diff --git a/planning/adr-0016-acceptance-verification-e2d54b2.md b/planning/adr-0016-acceptance-verification-e2d54b2.md new file mode 100644 index 0000000..56e747a --- /dev/null +++ b/planning/adr-0016-acceptance-verification-e2d54b2.md @@ -0,0 +1,26 @@ +# ADR-0016 acceptance-record verification — e2d54b2 + +- Date: 2026-08-31 +- Reviewed range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710` +- Result: `passed` +- Score: 7/7 goals verified + +## Verified + +- The human-acceptance basis names Jim Collinson, PR #98, and 2026-08-31. +- ADR-0015 permits an Accepted-status transition within an ADR's introducing pull request and places Accepted-ADR immutability at the default branch. +- Only authorized scopes changed. +- ADR governance passed with 1 ADR checked. +- All 20 governance tests passed. +- The diff check passed. +- At review time the pre-merge condition was that the remote needed the acceptance commits. That condition has since been satisfied, and CI associated with `e2d54b26e5d510419885345e22a2374d46aeb710` is green. + +## CI associated with e2d54b2 + +- Process-required ADR Governance run `33392124485`, job `99487983002`, was associated with head `e2d54b2` and ran on clean synthetic merge ref `c53dfc6d1b422099ed5dadb2406f0d8876409920`; checkout, all 20 tests, and governance passed. +- GitHub branch-protection-required prose run `33392124442`, job `99487983034`, sweep run `33392124448`, job `99487983102`, and sweep SHA reachability run `33392124434`, job `99487982641`, all passed as `not applicable` scope-gate no-ops with main validation skipped. +- Both GitBook statuses passed. + +## Findings + +None. diff --git a/planning/gsd-adr-0016-checkpoint.md b/planning/gsd-adr-0016-checkpoint.md index 811e21f..fe1ee7a 100644 --- a/planning/gsd-adr-0016-checkpoint.md +++ b/planning/gsd-adr-0016-checkpoint.md @@ -4,15 +4,15 @@ Date: 2026-08-31 Project: Autonomi Developer Documentation Slice/question: Should public documentation describe only stable software the public can obtain? Prepared by: orchestrator -Agents/tools used: operative, codereviewer, verifier, adversarial, Craft (passed); clean-context Jim-waived for ADR-0016 +Agents/tools used: operative, codereviewer, verifier, adversarial; prior proposal Craft passed; acceptance-record Craft not yet run; clean-context Jim-waived for ADR-0016 ## Status -Continue — Jim accepted ADR-0016 and authorized merge of PR #98 on 2026-08-31; complete final mechanical validation and final-head CI, then merge under that authorization. +Continue — ADR-0016 is Accepted by Jim and merge authorization is settled. Complete the final adversarial rerun, Craft Review, any needed focused consistency check, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head as mechanical gates, then merge PR #98 under Jim's 2026-08-31 authorization. Implementation remains unauthorized. Meaningful work-unit? Yes — the decision changes the durable public source-of-truth policy. -Review cadence: prior per-unit reviews completed; independent acceptance-record review, verification, and gauntlet checks precede merge -Unreviewed backlog: the acceptance-record update and final PR head; clean-context remains explicitly Jim-waived for ADR-0016 +Review cadence: acceptance-record code review and verification completed; exact-head adversarial review returned `NOT-READY`; rerun adversarial and Craft Review after this remediation +Unreviewed backlog: final adversarial rerun, acceptance-record Craft Review, focused consistency check as needed, and CI on the resulting final head; clean-context remains explicitly Jim-waived for ADR-0016 ## What happened @@ -29,21 +29,21 @@ No implementation, rendered docs, skill, CI, test, harness, or other ADR changed CI arbiter / green of record: - Location: PR #98, https://github.com/WithAutonomi/autonomi-developer-docs/pull/98 (open, non-draft) -- Rule: required checks on the current PR head are the green of record. -- Reviewed remediation head: `109101669908e7c7d86b3dc586a9b5b17933d2d6`; reviewed base: `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`. -- ADR Governance run `33376786646`, job `99439965340`: associated with the reviewed PR head and executed on clean synthetic PR merge ref `90806293682a5da7a3eeed72dfebd42f8f170f6e`; checkout, all 20 regression tests, and governance checks ran successfully. -- Prose run `33376786657`, job `99439965599`: successful scope-gate no-op (`not applicable`); main validation was skipped. -- Sweep run `33376786692`, job `99439965589`: successful scope-gate no-op (`not applicable`); main validation was skipped. -- Sweep SHA reachability run `33376786655`, job `99439965598`: successful scope-gate no-op (`not applicable`); main validation was skipped. +- Rule: process-required ADR Governance and GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final PR head are the green of record. ADR Governance is process-required but is not GitHub branch-protection-required. +- Reviewed acceptance head: `e2d54b26e5d510419885345e22a2374d46aeb710`. +- Process-required ADR Governance run `33392124485`, job `99487983002`: associated with head `e2d54b2` and executed on clean synthetic merge ref `c53dfc6d1b422099ed5dadb2406f0d8876409920`; checkout, all 20 tests, and governance passed. +- GitHub branch-protection-required prose run `33392124442`, job `99487983034`: green `not applicable` scope-gate no-op; main validation was skipped. +- GitHub branch-protection-required sweep run `33392124448`, job `99487983102`: green `not applicable` scope-gate no-op; main validation was skipped. +- GitHub branch-protection-required sweep SHA reachability run `33392124434`, job `99487982641`: green `not applicable` scope-gate no-op; main validation was skipped. - GitBook status `GitBook`: passed. - GitBook status `GitBook - docs.autonomi.com/developers/`: passed. -- Current PR required checks are the green of record. The final acceptance-record commit must receive green current-head checks before merge. +- The resulting final head after this reconciliation must receive green process-required ADR Governance and GitHub branch-protection-required checks before merge. Local fast gate / `.gsd/gate.sh`: - Installed? N/A — no `.gsd/gate.sh` exists. - ADR governance: passed, 1 ADR checked. -- Governance tests: passed, 20 tests. +- Governance tests: passed, 20/20 tests. - ant-sdk blob ref length check: passed, 31 refs checked and all are 40 characters. - `git diff --check`: passed. - Word count: 497. @@ -54,6 +54,9 @@ Artifacts: - `planning/released-antd-v0.11.2-audit.md` - `planning/STATE.md` - This checkpoint +- `planning/adr-0016-acceptance-code-review-e2d54b2.md` +- `planning/adr-0016-acceptance-verification-e2d54b2.md` +- `planning/adr-0016-acceptance-adversarial-e2d54b2.md` - Exact-SHA reports matching `planning/adr-0016-*.md` ## Honesty Rules @@ -61,39 +64,48 @@ Artifacts: - No-harness-modification: Pass. No gate, CI, test, build, or environment change. - Baseline-diff for evidence: Pass. No failure was dismissed. - Evidence reproducible-from-branch: Pass. -- Local vs CI consistency: Pass for the reviewed remediation. Merge is conditioned on final current-head green. +- Local vs CI consistency: Pass at reviewed head `e2d54b2`. Merge remains conditioned on green process-required ADR Governance and GitHub branch-protection-required checks on the resulting final head. ## Review Findings Code review: -- Concise ADR review at `752099a`: passed with no findings. -- Focused evidence-wording review at `fc49173`: ADR passed; the old checkpoint had one MEDIUM consistency finding. -- Disposition: replaced the old accumulated checkpoint with this concise current record. -- Focused review of the replacement checkpoint at `dcf7c8c`: passed with no findings. -- Attended code review of `7b8b537`: HIGH evidence-reproducibility finding; two GitHub compare calls in the audit targeted local-only commit `2e11cdc908a04d31bc35a6d998211cdb7949ce93` and failed remotely. Commit `6e9f056` removed those commands; re-review and current-head CI were pending at that point and are completed below. -- Re-review of `6e9f056`: MEDIUM CI-scope record issue and LOW clean-context waiver-date record issue. Commit `1091016` records prose, sweep, and sweep SHA reachability as successful scope-gate no-ops with substantive validation skipped and dates the waiver from commit `f3f3bdc`; final review and CI evidence follow below. -- Final review of remediation head `109101669908e7c7d86b3dc586a9b5b17933d2d6` against base `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3`: passed with no findings. Report: `planning/adr-0016-evidence-remediation-code-review-1091016.md`. +- Acceptance-record review range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`. +- Result: `passed` with no findings. +- ADR governance passed with 1 ADR checked; all 20 governance tests passed; diff and protected-scope checks passed. +- Only the three expected files changed. +- ADR-0016 changed only Status, Acceptance, and the final note. Its decision remained unchanged and the ADR contained 497 words. +- Acceptance, merge authorization, the final-head CI condition for process-required ADR Governance plus GitHub branch-protection-required checks, implementation prohibition, clean-context waiver, and default-branch immutability were coherent. +- Report: `planning/adr-0016-acceptance-code-review-e2d54b2.md`. Goal verification: -- Final concise verification at `58545cd`: passed 12/12 with no gaps. -- Later ADR change: one validation line aligned with an already-authorized evidence path; focused code review passed it. -- Final remediation verification: passed 10/10 goals. It confirmed exact 40-character ant-sdk refs, reachable representative URLs, unlinked local-only docs commits, removal of unreachable compare commands, accurate PR/base/merge and CI-scope records, coherent Craft/waiver records, no readiness overclaim, an unchanged ADR tree, and only three in-scope planning-file changes. Report: `planning/adr-0016-evidence-remediation-verification-1091016.md`. +- Verification range: `b0d01f41cc1a688699a3614ab4f3243362542a4f..e2d54b26e5d510419885345e22a2374d46aeb710`. +- Result: `passed`, 7/7. +- The human-acceptance basis names Jim Collinson, PR #98, and 2026-08-31. +- ADR-0015 permits an Accepted-status transition within an ADR's introducing pull request and places immutability at the default branch. +- Only authorized scopes changed; ADR governance, all 20 tests, and the diff check passed. +- At review time the remote needed the acceptance commits. That condition has since been satisfied, and CI associated with `e2d54b2` is green as recorded above. +- Report: `planning/adr-0016-acceptance-verification-e2d54b2.md`. Adversarial review: -- Review at `d18a63b`: READY-WITH-NITS; no CRITICAL, HIGH, or MEDIUM findings. -- Deployed-network validation wording nit: corrected in `dfe2161` and passed focused review. -- Stale PR-body nit: corrected. -- Final remediation review: `READY-WITH-NITS`; no CRITICAL, HIGH, or MEDIUM findings. LOW: living records lagged completed review and CI; the PR body claimed the ADR was ready but repeatedly used stale `draft` language while live PR #98 was open and non-draft. NIT: `exact-head CI` wording needed to distinguish PR-head association from synthetic-merge-ref execution. This record update resolves the living-status and CI-wording findings; the orchestrator will remove the stale `draft` wording from the PR body after final CI. The reviewer used OpenAI GPT-5.6-sol, the same model as the earlier pass; the implementer provider is unrecorded, so model-independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-adversarial-1091016.md`. +- Required: Yes. +- Result: `NOT-READY` at exact head `e2d54b26e5d510419885345e22a2374d46aeb710`. This reconciliation commit remediates the recorded findings; final adversarial rerun has not passed yet. +- HIGH: the live PR body contradicted acceptance and merge authorization and had stale head, count, and merge-ref evidence. Disposition: the orchestrator corrected the live PR body before this commit. +- MEDIUM: state and checkpoint still marked completed code review, verification, and CI pending and lacked branch-local code-review and 7/7 verification reports. Disposition: this commit reconciles both records and adds the reports. +- LOW: generic `required checks` wording obscured that ADR Governance is process-required but not GitHub branch-protection-required; branch protection requires only prose, sweep, and sweep SHA reachability, all `not applicable` no-ops here. Disposition: this commit uses explicit wording. +- No content or governance failure: the ADR decision remained unchanged at 497 words, local checks passed, and ADR-0015 alignment was correct. +- Reviewer: OpenAI GPT-5.6-sol, the same provider/model as the earlier review. The implementer provider is unrecorded, so independence evidence is weaker. +- Report: `planning/adr-0016-acceptance-adversarial-e2d54b2.md`. Craft Review: - Required: Yes. -- Result: Pass at `dcf7c8c`; no CONFORMANCE, SIMPLICITY, or NIT findings. -- Report: `planning/adr-0016-craft-dcf7c8c.md`. -- Final remediation result: PASS in fresh context; no CONFORMANCE, SIMPLICITY, or NIT findings. The reviewer used the same OpenAI GPT-5.6-sol model/provider as the earlier pass; the implementer provider is unrecorded, so independence evidence is weaker. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. +- Previous proposal result: Pass at `dcf7c8c`; no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-craft-dcf7c8c.md`. +- Previous evidence-remediation result: Pass at `1091016`; no CONFORMANCE, SIMPLICITY, or NIT findings. Report: `planning/adr-0016-evidence-remediation-craft-1091016.md`. +- Acceptance-record result: Not run. The exact-head adversarial `NOT-READY` result blocked it. +- Final Craft Review after this remediation is a mandatory merge condition and has not passed yet. Clean-context review: @@ -114,18 +126,18 @@ Merge commit `42b5bfef3bde33ff785fa28cb03fb0e3038d05c3` integrated current base ## Open Questions / Decisions for Jim -No further acceptance or merge decision is pending. Jim accepted ADR-0016 and authorized merge of PR #98 on 2026-08-31. Final validation and required checks on the final PR head remain mechanical pre-merge conditions. This authorization does not authorize implementation. +No further acceptance or merge decision is pending. ADR-0016 is Accepted by Jim, and Jim authorized merge of PR #98 on 2026-08-31. Final adversarial rerun, Craft Review, a focused consistency check as needed, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head are mechanical pre-merge conditions. This authorization does not authorize implementation. PR / upstream action gate: - PR status: already open and non-draft. -- Merge ready? Conditional on final validation and required final-head CI being green. +- Merge ready? No — conditional on final adversarial rerun, Craft Review, any needed focused consistency check, and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head. - Jim authorized merge? Yes — on 2026-08-31. ## Recommended Next Step -Run local validation, independent acceptance-record review, verification, and gauntlet checks, then obtain green required checks on the final PR head and merge PR #98 under Jim's authorization. Do not begin implementation. +Run the final adversarial rerun, Craft Review, and a focused consistency check as needed. Then obtain green process-required ADR Governance and GitHub branch-protection-required prose, sweep, and sweep SHA reachability checks on the resulting final head and merge PR #98 under Jim's authorization. Do not begin implementation. ## Handoff Note -The concise ADR and evidence remediation passed final code review, goal verification, adversarial review, and Craft Review. Clean-context remains explicitly Jim-waived for ADR-0016. Jim accepted ADR-0016 and authorized merge of PR #98 on 2026-08-31. Complete acceptance-record review and verification, final-head CI, and merge; do not begin implementation. Once merged, ADR-0016 is immutable and later changes require a superseding ADR. +ADR-0016 is Accepted by Jim, and merge authorization is settled. Acceptance-record code review and 7/7 verification passed, and CI associated with `e2d54b2` is green. Exact-head adversarial review at `e2d54b2` returned `NOT-READY`; this commit remediates its PR-body, living-record, report, and CI-wording findings. Final adversarial rerun and Craft Review remain mandatory, with a focused consistency check as needed and green process-required ADR Governance plus GitHub branch-protection-required checks on the resulting final head. Clean-context remains explicitly Jim-waived for ADR-0016. Do not begin implementation. Once merged, ADR-0016 is immutable and later changes require a superseding ADR.