docs(adr): reconcile freshness, authority, and current state

[JimCollinson]

Summary

Documentation-only decision and current-state update. This revision resolves David Irvine's four requested changes, replaces the proposed in-skill self-version check with channel-owned update delivery, and keeps every changed ADR Proposed for renewed human review.

No skill implementation, installation manifest, CI workflow, test harness, repository visibility, or Accepted ADR changes in this PR.

Decisions and corrections

• Channel-owned updates: Proposed ADR-0013 now assigns installed-skill update discovery and delivery to the installation channel, or deliberate reinstall for a manual copy. The skill makes no request solely to check its own version, does not inspect manager state, and does not modify itself. A pin means a commit SHA or channel-enforced immutable release identifier; a branch or other mutable ref follows the channel's update semantics.
• Typed live values remain separate: ADR-0013 mechanism 4 is a deferred, bounded design for signed, typed operational values only. It is not a skill-version check, never fetches free-form instructions, and remains blocked on an authoritative values document plus a detailed protocol/spec.
• Authority gates are universal; routes vary: Proposed ADR-0014 now requires identical authority and safety gates across a present human, a proxy agent, and a fully autonomous agent, while disclosure and escalation routing adapt to the supplied context.
• No mutation without remit: missing, ambiguous, or exceeded remit permits only necessary non-mutating observation to establish state and authority. Install/upgrade, start/stop, delete/reset, volume selection, and spend require affirmative remit.
• Within-envelope action remains autonomous: Proposed ADR-0010 distinguishes granting or widening authority from acting inside an existing envelope. The latter needs no per-action human approval; unreachable authority gates are deferred rather than crossed. ADR-0013 separately prevents a newly fetched material value from widening the approved policy baseline without human approval.
• Provenance exceptions are accountable: Proposed ADR-0006 now distinguishes normal upstream source bindings from temporary team-confirmed records. The existing ~20 GB recommendation is recorded in the manifest with Jim's dated repository record, its unresolved additive/shared semantics, and the route to replace it with upstream authority.
• Platform evidence is a requirement, not a completed claim: ordinary shell/OS guidance must be checked for each claimed platform. Most unchanged operational recipes are Bash-oriented, including disk and balance procedures, and provisioning, troubleshooting, and uninstall contradict the source-bound installer on whether Windows PATH is updated. README and HANDOFF therefore mark these as known examples rather than an exhaustive Windows audit, while the active resource brief records the correct Unix/Windows distinction.
• Active documents reconciled: Proposed ADR-0006/0008/0011, DESIGN, operating doctrine, VISION, FEATURES, SECURITY, CONTRIBUTING, HANDOFF, NEXT-PHASE, ROADMAP, and the historical/current-state labels now use the same boundaries and state current verification limits accurately.
• Research retained: planning/channel-update-research.md records fixed revisions, per-collection counts and documentation paths, a reproducible method, and the distinct global/project skills.sh updater paths.

Current implementation boundary

This PR deliberately retains the current 0.1.0 skill and its legacy metadata.openclaw block. OpenClaw's current parser ignores the block's unsupported shell / powershell installer entries and command / verifies fields, so no working OpenClaw installer or public ClawHub listing is claimed. No Claude Code plugin or PR #13 implementation is claimed here, and checksum/signature verification through the current script route is not implemented. README therefore labels the skill an internal preview.

The unchanged installed skill still contains older "smaller, reversible action" wording, over-broad “every command and figure” provenance wording, and the Windows guidance defects described above. Proposed ADR-0014 and the clarified ADR-0006 are reviewed target policy, not a claim that this docs-only PR has already implemented them. Implementation reconciliation belongs to PR #13 after this decision PR lands.

Verification at current head

Current head: c8ecb644ac366d5a2b9965ad1e3b95405e75ea56.

• GITHUB_BASE_REF=main python3 scripts/adr-governance.py passes (14 ADR file(s) checked).
• git diff --check origin/main...HEAD passes.
• All changed ADRs remain Proposed; no Accepted ADR changed.
• All nine fixed-revision research links resolve.
• Exact-head GitHub ADR Governance CI passes (run).
• Exact-head verifier, adversarial semantic review, Craft Review, and supplementary fresh-context read pass.
• Jim dispositioned the broader ADR findings: do not expand this PR; keep every ADR Proposed, use PR feat(autonomi): land the task-routed prototype (0.1.4 install/freshness repair) #13's prototype as evidence, then amend the Proposed records. Direction for later reconciliation is bundled operational core with optional external depth, and recovery required for every agent-created wallet.
• Official Fable was not run by Jim's explicit direction. The unrelated stale WithAutonomi/brand lock was retired without deleting its evidence; a manual Hermes review replaces that route for this checkpoint.
• Manual Hermes review: pending.
• Renewed approving human review: required before merge.

GitHub ADR Governance is the CI green of record, but it checks ADR structure and immutable Accepted status rather than semantic correctness.

Scope and provenance

Original documentation authored by Jim Collinson with agent assistance. The review remediation was authored through OpenCode using GPT-5.6 Sol under Jim's direction. The work packet is planning/packets/2026-Sep-05-pr12-review-remediation.md.

Exact-head automated checks and Jim's ADR/Fable dispositions are recorded. Manual Hermes and renewed approving human review remain pending, so this is not ready to merge. Do not merge, accept ADRs, publish, or change repository visibility without the remaining human decisions.

[dirvine]

ADR review — head 2a50105f

Verdict: changes recommended before merge. The direction is good: separating production, consumption and volatile-data freshness is the right model. The six-reviewer pass was 5–1 on merge readiness: five recommend revision now; one would merge ADR-0013 as Proposed, but agreed it must not be Accepted or implemented as written.

Required

1. Fix the consumer-update identity in ADR-0013.

   ADR-0013:30,43,46,78,84 treats frontmatter version as what drives npx skills update. The current Vercel CLI does not use it that way. At vercel-labs/skills head cf4a3ea6, updates are based on stored source/ref/path and skill-folder/content hashes, then re-installation (src/update.ts:300-374,443-476,487-638; src/skill-lock.ts:15-35; src/local-lock.ts:15-37). A frontmatter change happens to alter the hash, but there is no semantic-version comparison or published-version lookup.

   Define currency as authenticated source identity + release/ref + artifact digest. If frontmatter SemVer is to become the cross-channel key, describe that as a new self-check contract rather than as current skills.sh behaviour. Also clarify that an immutable installed tag will remain pinned unless update discovery deliberately moves to a newer release.

2. Specify mechanism 4 as a trust protocol, not merely an “integrity-pinned source”.

   ADR-0013:48-58 leaves the load-bearing properties open. A fixed content digest cannot update; a pinned publisher identity can, but then the ADR needs the minimum contract: signed/versioned envelope, bundled trust root, canonical encoding/schema, key rotation/revocation, monotonic ordering/expiry, replay/downgrade rejection, authorised rollback, and explicit handling for malformed, unverifiable or conflicting responses.

   Keep live material typed and data-only. Signing proves who published content; it does not make free-form “advice” safe to inject into an agent’s instructions. The structured values block proposed in planning/node-resource-spec-brief.md:119-121 is the sound boundary; judgement-derived prose should remain reviewed bundle content.

   Also resolve the policy contradiction: ADR-0013:49 says “reachable → prefer it”, while :54 and :85 say fetched values are never silently/automatically applied. Define materiality, approval, unavailable-human behaviour, and when stale bundled values may support existing operation but must not authorise consequential scaling.

3. Reconcile ADR-0013 with the existing decision set.

   • ADR-0013:46,58 makes the channel-independent self-check optional, while ADR-0008:35 already requires one and DESIGN:61-63 describes it. Either mandate it or explicitly amend the earlier decision; otherwise the claim of channel independence at ADR-0013:65 is not true.
   • ADR-0013:42-43 implies blanket regeneration/re-release of SKILL.md and references, while ADR-0006:32-35 says mechanical content may regenerate and judgement-derived content must be flagged for review. Preserve that split and add a reviewed release/promotion gate.
   • planning/REBUILD-BRIEF.md:79 explicitly says no runtime live-fetch. ADR-0013 can change that proposal, but should record the reversal rather than leave two current contracts.

4. Complete ADR-0010’s treatment of the new decisions.

   The additions at ADR-0010:35,39,48-50—no surfaced autonomy tiers, no internal/build vocabulary, and judgement-based rather than mechanical translation—are sensible. However, the drivers/options/consequences/validation at :15-27,53-73 still cover mainly the older disclosure/register decision.

   Either retain the rebuild brief’s plan for separate Proposed ADRs, or expand ADR-0010 so each addition has rationale, alternatives, trade-offs and tests. Add a mode-free default-deny rule for missing/ambiguous remit: least authority, safe reversible action only, otherwise ask/escalate/defer. Validation should exercise all three personas without self-classification and check the shipped product-facing boundary for forbidden build/process language. Define that boundary explicitly.

5. Fix the living handoff in this PR.

   planning/HANDOFF.md still says ADR-0001–0012 only (:14), calls freshness a candidate ADR (:51), and says the ADR-0010 tightening is not authored (:53). Those statements become false on merge and are the clearest immediate merge blocker.

Checks

• ADR governance: pass — 13 ADRs
• git diff --check: pass
• GitHub ADR CI: pass
• PR head revalidated at 2a50105f7203bc33dff54a5367c393dde3fb3714
• Scope is documentation only; no shipped skill/runtime behaviour changed

[dirvine]

ADR re-review — head 7f3b2e2

Verdict: much improved; two small semantic corrections remain before merge.

The six-reviewer pass split 3–3 between merge-ready and conditional/block. I independently checked the disputed points. The earlier major findings are now substantially resolved: the current skills.sh identity/hash behaviour is described accurately; mechanism 4 is typed/data-only with explicit trust and human-approval boundaries; the ADR-0006 regeneration split is preserved; the live-fetch reversal is recorded; ADR-0014 cleanly separates autonomy/remit/product-surface concerns; and HANDOFF is current.

Required

1. Separate the current channel updater from the channel-independent self-check in ADR-0013.

   ADR-0013:48 accurately describes the current Vercel CLI: stored source/ref/path plus a folder hash. I rechecked this against vercel-labs/skills head 5527c09 (src/skill-lock.ts:15-31,181-201; src/local-lock.ts:15-35; src/update.ts:300-407).

   The remaining jump is at ADR-0013:50,65,71: a skills.sh lock entry is channel-specific and need not exist for a native/direct copied bundle, yet the text calls the resulting self-check channel-independent and defers whether its currency key is frontmatter version or install identity/hash. Please define the minimum cross-channel contract separately — e.g. the bundle carries a canonical publisher/source identity plus its release/artifact identity, and checks a defined authenticated publication pointer. Channel-native lock/hash updating can remain one implementation; it is not itself the cross-channel contract.

   Also update planning/NEXT-PHASE.md:26-28, which still says the model is undecided and repeats the now-corrected claim that skills.sh updates through the frontmatter version. ADR-0013 points readers there for implementation, so leaving it stale recreates the ambiguity the ADR fixes. docs/DESIGN.md:61-63 and planning/ROADMAP.md:77-87 should either be aligned or explicitly marked as superseded planning.

2. Tighten ADR-0014’s validation wording.

   ADR-0014:66 says safety/escalation behaviour is identical across all three personas. The authority gates should be identical, but the escalation path is deliberately not: ADR-0010:35 / DESIGN:89-112 distinguish a present human, a proxy escalating to its principal, and an autonomous agent escalating asynchronously or deferring when nobody is reachable. Validate identical authority/safety gates, with disclosure and escalation routing appropriate to the supplied context — never a self-declared tier.

Non-blocking / correctly deferred

• Mechanism 4's envelope schema, cryptographic primitive, rotation procedure and materiality schema should be fixed before implementation/Acceptance, but they do not block merging a Proposed ADR: ADR-0013:71,85-93 explicitly defers and gates that mechanism.
• ADR-0014's product-surface boundary currently holds: an exact scan of skills/autonomi/SKILL.md plus references/*.md found 0 hits for the stated forbidden vocabulary. CI linting would make this durable, but absence of that future enforcement is not a current semantic blocker.

Checks

• ADR governance: pass — 14 ADRs
• git diff --check: pass
• GitHub ADR CI: pass
• Current shipped-surface forbidden-vocabulary scan: 0 hits
• PR head revalidated at 7f3b2e2690975184ab88aba3910cbbe05b597812
• Docs-only; no shipped skill/runtime behaviour changed

Once the two wording/reconciliation points above are fixed, I would be comfortable with merging these as Proposed. Acceptance of ADR-0013 should still wait for the cross-channel identity and mechanism-4 protocol details to be concrete enough to test.

[dirvine]

Addendum to the re-review — two further authority conflicts

The delayed independent ADR reviewers completed after my review was posted. I checked their substantive findings against ADR-0004/0009 and DESIGN §13; two are valid and raise the verdict from “two small corrections” to request changes before merge. Please read this together with the review above.

3. Default-deny must not permit mutation outside remit

ADR-0014:36,43,67 currently allows a “least-authority, safe, reversible action” when remit is missing, ambiguous or would be exceeded. Safety/reversibility does not grant authority. This conflicts with:

• ADR-0009:19,30,58: mutate only within granted remit; escalate rather than mutate outside it.
• ADR-0008:33: upgrades/mutations only within granted remit.
• ADR-0004:23,57,71: least privilege and explicit remit envelopes.

Please distinguish observation from mutation:

• missing/ambiguous remit → only permitted non-mutating observation needed to establish state/authority;
• exceeded remit → do not perform the proposed action;
• consequential/state-changing action → affirmative remit, otherwise ask/escalate/defer;
• any emergency containment exception needs a separately defined authority source and narrow bounds.

Validation should cover concrete cases: install/upgrade, start/stop, delete/reset, external-volume selection, spend, and read-only status/balance checks.

4. “Always surfaced to the human” conflicts with pre-authorised autonomous operation

ADR-0010:33,42,69 says money/risk/recovery/consent decisions are always surfaced to a human/every time, and DESIGN:116 mirrors it. That conflicts with:

• ADR-0004:57: spend is controlled by granted envelopes, not per-action human approval;
• DESIGN:90-94: an autonomous agent may have no human in the operational loop and may have no reporting channel;
• ADR-0010:35: absent a human, the agent defers only at a gate it cannot cross.

Please separate:

1. authority/envelope decisions or changes — must be explicitly granted or escalated, never inferred;
2. within-remit actions — may proceed without per-action human approval;
3. reporting/disclosure — adapted to the available channel, with audit where required;
4. an unreachable authority gate — halt/defer rather than cross it.

This also reinforces the earlier correction to ADR-0014:66: authority gates are invariant across personas; escalation route, timing and disclosure are not.

Updated verdict

Not merge-ready at head 7f3b2e2. Required before merge:

1. separate channel-native lock/hash updating from the cross-channel self-check and reconcile the stale planning/docs;
2. make ADR-0014 validation preserve identical authority gates, not identical escalation behaviour;
3. prohibit state mutation where remit is missing/ambiguous/exceeded;
4. reconcile “always surfaced” with pre-authorised within-envelope autonomous action.

The mechanism-4 wire protocol and durable vocabulary lint remain pre-Acceptance/implementation work, not blockers to merging the ADRs as Proposed.