diff --git a/.github/SECURITY.md b/.github/SECURITY.md index c7e7db1..1a185ee 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -6,10 +6,10 @@ This repository is an **operator skill**: documentation and skill files that ins ## Security posture -- **Non-custodial by construction.** Nodes are configured with a **public** wallet (rewards) address only. The skill never generates, stores, requests, logs, or transmits a private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` (ADR-0004). Any future spend/custody capability lives in an out-of-context substrate — never in the agent context, the skill, or this repo. +- **Non-custodial by construction.** Nodes are configured with a **public** wallet (rewards) address only. The current skill generates, stores, requests, logs, and transmits no private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` (ADR-0004). Any future spend/custody capability requires a separately approved substrate that keeps secrets outside the agent context; ADR-0004 deliberately leaves that substrate's implementation location open. - **No secrets in the repo.** Never commit a private key or secret in code, examples, fixtures, or logs. If one is ever exposed, treat it as compromised: abandon/rotate the affected address and remove the secret from history. -- **Source-bound, no invented surface.** Commands, flags, and install steps are pinned to upstream source (ADR-0006); installs are detect-first and non-mutating (ADR-0009). This limits the chance of the skill instructing an unsafe or fabricated action. -- **Verified distribution.** Install steps and releases verify checksums and signatures before use (ML-DSA-65 / FIPS-204; `SHA256SUMS`), and the package is built to pass distribution-channel security scans (ADR-0008). +- **Source-bound, no invented Autonomi surface.** Autonomi-specific commands, flags, constants, figures, and install behaviour carry explicit provenance under ADR-0006; ordinary operating-system/shell observation commands are not presented as Autonomi facts and **must be** reviewed for every claimed platform. The current Windows guidance has known unverified gaps recorded in `planning/HANDOFF.md`. Installs are detect-first and do not mutate an existing working setup by default (ADR-0009). This limits the chance of the skill instructing an unsafe or fabricated action. +- **Distribution verification is a required target, not a current guarantee.** Upstream releases provide ML-DSA-65 / FIPS-204 signatures and `SHA256SUMS`, but the current script-based install route does not verify them before execution. Until every supported route performs and proves checksum/signature verification, contributors and documentation must not claim verified delivery (ADR-0008). ## Reporting a vulnerability diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6969870..a71b179 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -30,11 +30,11 @@ The aim: a reviewer — human or agent — can understand this PR and sanity-che - [ ] No secrets in the diff — no private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` in code, examples, or logs. - [ ] Non-custodial boundary intact — nodes take a public wallet (rewards) address only; nothing instructs putting a key on a node or in the repo (ADR-0004). -- [ ] Install stays detect-first and non-mutating; any download/verify step is documented and source-bound (ADR-0009). +- [ ] Install stays detect-first and does not mutate an existing working setup by default; any download/verify step is documented and source-bound (ADR-0009). ## Quality & verification -- [ ] Every command, flag, constant, and figure is pinned to upstream source (repo / file / symbol / commit); nothing invented — anything unconfirmable is flagged, not guessed (ADR-0006). +- [ ] Every Autonomi-specific command, flag, constant, figure, and install behaviour has explicit provenance; temporary team-confirmed exceptions are labelled pending upstream authority, and platform-specific shell/OS behaviour is checked rather than guessed (ADR-0006). - [ ] `python3 scripts/adr-governance.py` passes. - [ ] Gauntlet (for merge-candidate skill changes): clean-context test + adversarial review — - [ ] Docs updated (DESIGN / README / references) if a surface or behaviour changed. @@ -44,7 +44,7 @@ The aim: a reviewer — human or agent — can understand this PR and sanity-che - [ ] Frontmatter valid and complete — name, description, version, license, keywords. -- [ ] Install manifest (`metadata.openclaw.install`) correct; install and clean-uninstall paths documented; signature/checksum verification intact (ADR-0008). +- [ ] Install manifest (`metadata.openclaw.install`) correct; install and clean-uninstall paths documented; the current signature/checksum verification status is stated accurately, and any implemented verification remains intact (ADR-0008). - [ ] Won't break packaging, and should pass distribution-channel security scans (e.g. ClawHub). ## For reviewers diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 93efcaf..1c74ffa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,12 +7,12 @@ Contributors are humans and AI agents alike; these conventions keep the trail re ## Ground rules - **Never commit a secret.** No private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` in code, examples, or logs — nodes use a **public** wallet (rewards) address only (ADR-0004). See [`.github/SECURITY.md`](.github/SECURITY.md). -- **Source-bind every claim.** Commands, flags, constants, and figures are pinned to upstream source (repo / file / symbol / commit). Don't invent — if it isn't confirmable in source, flag it rather than guess (ADR-0006). +- **Bind every Autonomi claim to provenance.** Autonomi-specific commands, flags, constants, figures, and install behaviour normally pin to upstream source (repo / file / symbol / commit). Temporary team-confirmed exceptions are explicit and pending upstream authority. Ordinary operating-system/shell observation commands are not Autonomi claims, but platform-specific behaviour must still be checked rather than guessed (ADR-0006). - **Decisions go through ADRs.** Architectural, protocol, security, or storage changes add or update a **Proposed** ADR before merge; Accepted ADRs are immutable (supersede, don't edit). See [`docs/adr/README.md`](docs/adr/README.md). ## Branch & PR flow -- `main` is protected and always stable. Do all work on a short-lived branch off `main`. +- Project policy treats `main` as protected and stable: do all work on a short-lived branch off `main`. GitHub's configured ruleset is not technically enforced while this private repository is on the organisation's free plan; see `planning/HANDOFF.md` for the current enforcement state. - Branch names: `feat/…`, `fix/…`, `docs/…`, `chore/…` (or `name/topic` for personal / WIP branches). - Commits follow [Conventional Commits](https://www.conventionalcommits.org): `feat`, `fix`, `docs`, `chore`, `refactor`, `test` — e.g. `feat(tier1): add node preflight checklist`. - Open a PR into `main` using the [pull request template](.github/pull_request_template.md). Fill in what's relevant; delete what isn't. diff --git a/README.md b/README.md index f9b612d..60a78a0 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,14 @@ This is the home for Autonomi's first-party skills. It holds one or more skills | Skill | What it's for | Status | | --- | --- | --- | -| **`autonomi`** | Run and manage Autonomi nodes, and earn ANT (the Autonomi Network Token) for the storage they provide. Non-custodial. | **Available** | +| **`autonomi`** | Run and manage Autonomi nodes, and earn ANT (the Autonomi Network Token) for the storage they provide. Non-custodial. | **Internal preview** | | `autonomi-developer` | Build applications *on* Autonomi (libraries, SDK). | Planned — currently at [`WithAutonomi/autonomi-developer-docs`](https://github.com/WithAutonomi/autonomi-developer-docs) | ## Install The skill is standards-compliant ([agentskills.io](https://agentskills.io)), so it isn't tied to one channel. -### skills.sh (from GitHub) +### skills.sh (from GitHub; repository access required while private) ```bash # Install the autonomi skill (it's the only one here, so a bare add installs it) @@ -27,18 +27,21 @@ npx skills add WithAutonomi/skills --skill autonomi Useful flags: `--skill ` (pick a specific skill), `--all` (install all), `-a ` (target agent, e.g. `opencode`, `claude`, or `*` for all), `-g` (install globally), `-l` (list without installing), `-y` (no prompts). When the repo holds more than one skill, a bare `add` opens an interactive picker keyed on each skill's name + description. -### ClawHub / OpenClaw +### ClawHub / OpenClaw (future; current installer metadata is unsupported) ```bash +# Intended command once compatible metadata is shipped and the skill is listed openclaw skills install autonomi ``` -The skill carries an OpenClaw install manifest in its frontmatter (`metadata.openclaw`) describing how to fetch and verify the upstream `ant` binary. +The frontmatter contains a legacy `metadata.openclaw` block, but its `shell` and `powershell` installer kinds and its `command` / `verifies` fields are not supported by OpenClaw's current [installer contract](https://github.com/openclaw/openclaw/blob/de2c4b1768d9babd158c49d83aa91b67eff50dbc/src/skills/types.ts#L4-L19) and are ignored by the [parser](https://github.com/openclaw/openclaw/blob/de2c4b1768d9babd158c49d83aa91b67eff50dbc/src/skills/loading/frontmatter.ts#L108-L121). No working OpenClaw installer or public ClawHub listing is claimed. The current script path also lacks checksum/signature verification; compatible metadata, publication, and secure-delivery proof remain open work. ### What gets installed The **skill bundle** — `skills/autonomi/SKILL.md` plus its bundled `references/`. The skill is agent-facing instructions; on first use it guides the agent to install the upstream **`ant`** CLI (the Autonomi tool) itself, non-custodially. Nothing here holds keys or moves funds. +> **Platform status:** no platform has completed the full live release test. Windows remains unverified: most operational recipes are Bash-oriented, including disk checks and the read-only balance procedure, and provisioning, troubleshooting, and uninstall incorrectly say the Windows installer does not update `PATH`. Treat these as known examples, not an exhaustive Windows audit; see `planning/HANDOFF.md`. + > **Heads-up — binary install in locked-down sandboxes.** The `ant` installer downloads its binary from GitHub's release CDN (`release-assets.githubusercontent.com`), which some AI-agent sandboxes block even when `github.com` is allowed. The skill detects this and tells you exactly what to allowlist rather than failing silently. Tracked as an upstream/release item in [`planning/release-endpoint-accessibility.md`](planning/release-endpoint-accessibility.md). ## Repo layout @@ -52,7 +55,7 @@ skills// # the installable skill bundle(s) — the ONLY thing tha docs/ # repo-side, never ships adr/ # architecture decision records planning/ # briefs, handoff, open threads -source-bindings/ # provenance: every command/figure bound to upstream code (drives auto-update) +source-bindings/ # provenance for commands/sourced figures; drives release regeneration scripts/ # maintenance / freshness automation ``` diff --git a/docs/CURRENT.md b/docs/CURRENT.md index 0d5a68e..22f20f6 100644 --- a/docs/CURRENT.md +++ b/docs/CURRENT.md @@ -1,4 +1,6 @@ -# GSD Checkpoint — Autonomi Operator Skill (current state) +# GSD Checkpoint — Autonomi Operator Skill (2026-Jun-22 snapshot) + +> **Historical checkpoint.** This file preserves the state recorded on 22 June 2026 and is not the current entry point. Read `planning/HANDOFF.md` for current state and next actions. Date: 2026-06-22 Project: Autonomi Operator Skill (`JimCollinson/autonomi-skill`) @@ -6,7 +8,7 @@ Slice/question: Design phase (engine, personas, grounding) complete and merged t Prepared by: Cowork (Claude) orchestration, on Jim's behalf Agents/tools used: Cowork (Claude); deep source-research subagents against `WithAutonomi/*` and `saorsa-labs/*`; GitHub; Autonomi canonical docs (`autonomi.com/llms.txt`). -> **Read this first if you are the incoming agent.** Fetch the real `main` (tip below) before doing anything — design and docs were updated via reviewed PRs, so a stale local clone may be missing files. Follow the coordination protocol in `CONTRIBUTING.md` (lanes; branch + PR, never commit to `main` directly; fetch/rebase before a session and after each merge). Reading order: `README.md` → `docs/VISION.md` → `docs/DESIGN.md` (esp. §13) → `docs/adr/` → `docs/operating-doctrine.md` → `docs/skill-grounding.md` → `SKILL.md` + `references/` + `source-bindings/tier1-operate-and-earn.md` → `planning/ROADMAP.md`. +> At this checkpoint, the reading order was: `README.md` → `docs/VISION.md` → `docs/DESIGN.md` (esp. §13) → `docs/adr/` → `docs/operating-doctrine.md` → `docs/skill-grounding.md` → `SKILL.md` + `references/` + `source-bindings/tier1-operate-and-earn.md` → `planning/ROADMAP.md`. ## Status @@ -59,7 +61,7 @@ Adversarial review: - ADRs are **Proposed, not Accepted** — acceptance is a human gate (Jim decision-owner, after review). Never mark Accepted autonomously; supersede, don't edit. - **Tier 2/3 are gated** on the custody (ADR-0004) and gas (ADR-0005) team decisions — do not start them; the build round stays in **ungated operate-and-earn**. -- `docs/SOURCE-MAP.md` has minor stale bits: it still calls the close-group size "5 and 7" (resolved to **7**) and says "evmlib not needed for Tier-1" (the key-free balance read does use evmlib as provenance). Tidy in a later pass. +- The stale SOURCE-MAP orientation noted at this checkpoint (close-group size and Tier-1 `evmlib` provenance) is corrected in PR #12's current-state reconciliation. - The full source-research synthesis is held in Cowork's working notes (not the repo); the repo carries the conclusions (doctrine, manifest, DESIGN). ## Open questions / decisions for Jim diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 1488616..24050e3 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -1,6 +1,6 @@ # Autonomi Operator Skill — Design -> Canonical design, realigned to ADR-0001…0009. This supersedes the original pre-decision scaffold (which framed the work as a single "loop" and assumed a gas-abstraction path — both removed). Loose thinking lives in the vault (`Projects/Autonomi Skill`); this is the formal design. Volatile specifics (flags, constants, addresses, URLs) are **source-bound** to upstream per ADR-0006, not hardcoded here. +> Canonical design target, not an exact inventory of the currently shipped files. Read `planning/HANDOFF.md` and `README.md` for implementation state. This supersedes the original pre-decision scaffold and is aligned with the repository's Proposed ADRs; none is Accepted autonomously. Volatile specifics (flags, constants, addresses, URLs) carry explicit provenance per ADR-0006: normally an upstream source binding, or a visibly provisional team-confirmed record pending upstream authority. ## 1. Purpose and shape @@ -60,7 +60,7 @@ Three buckets the skill keeps distinct: **what the network enforces** (facts the ## 10. Staying current (ADR-0006) -Every claim is **source-bound** to upstream (repo / file / symbol / commit) via a source-binding manifest; volatile facts are isolated and single-sourced; content is tagged mechanically-derived (auto-regenerable) vs judgement-derived (flag-for-review); per fact, a deliberate bake-with-pin vs fetch-live choice. An in-skill **version self-check** fetches a manifest from an Autonomi-controlled URL and warns if stale, continues if offline. Upstream repos signal operator-facing changes back to the skill (the cross-repo freshness contract, ADR-0006). The automation pipeline (upstream-sweep) is deferred; the regeneration-ready structure is mandatory now. +Every Autonomi-specific factual claim carries explicit provenance in the source-binding manifest: normally an upstream repo / file / symbol / commit, or a visibly provisional team-confirmed record pending upstream source (ADR-0006). Ordinary operating-system/shell behaviour must use appropriate platform evidence outside that manifest before support is claimed. Volatile facts are isolated and single-sourced; content is tagged mechanically-derived (auto-regenerable) vs judgement-derived (flag-for-review); per fact, a deliberate bake-with-pin vs approved, bounded fetch-live choice. New skill versions are delivered by the channel that installed them, or by deliberate reinstall for a manual copy (ADR-0013). The skill does not make a network request to check its own version. A separate, optional live check may fetch only signed, typed volatile values within granted network/egress remit, falling back to the bundle otherwise (ADR-0013). Upstream repos signal operator-facing changes back to the skill (the cross-repo freshness contract, ADR-0006). The automation pipeline (upstream-sweep) is deferred; the regeneration-ready structure is mandatory now. ## 11. Metadata, licensing, provenance (ADR-0008) @@ -113,7 +113,7 @@ The skill stays honest about the boundary at every tier: *it can operate nodes a ### Disclosure & division of labour -Default to doing the work; surface outcomes and genuinely-human choices; keep mechanics and jargon out of the way. Minimise *operational* burden, never *authority* — spend / risk / recovery / consent are always surfaced (ADR-0004/0009 risk-based escalation). Escalate by exception, not for routine ops, and never on crypto-literacy. +Default to doing the work; surface outcomes and genuinely authority-gated choices; keep mechanics and jargon out of the way. Minimise *operational* burden, never *authority* — but "authority" means **granting or widening an envelope**, not acting within one. A spend / risk / recovery / consent envelope is explicitly granted by, or its widening escalated to, the **authorised principal/delegator**; it is never inferred. **Acting within a granted envelope** needs no per-action approval (ADR-0004/0009), and reporting adapts to the available channel. Human-only gates remain human: in particular, ADR acceptance and ADR-0013's material live-value approval cannot be delegated to the running agent. Escalate by exception, not for routine ops, and never on crypto-literacy; where the authorised decision-maker can't be reached, **halt/defer** rather than cross the gate. ### Language register @@ -131,11 +131,11 @@ Plain, not patronising — assume intelligence, not specialist knowledge. Lead w ## 14. Open questions (carried; mostly David/maintainer) -- GitHub home/org and clean install URL; published skill name; version-manifest hosting URL. +- Release/promotion mechanics and clean install/update verification for each supported channel. - Agent wallet custody substrate (where keygen/storage/recovery/signing live: assumed-host / signposted / skill-provided wrapper / upstream `ant`) — open team decision (relates to ADR-0004). - Gas / acquisition easing (DEX guidance, a paymaster if one returns) — escalate to David (ADR-0005). - Upstream watch-set and "material change" policy (for the deferred automation). -- Pin volatile constants or fetch-live (e.g. the close-group size — read as both 5 and 7; resolve before authoring). +- Publish the authoritative Recommended Node Resource Document and define ADR-0013 mechanism 4's detailed protocol/spec before implementing any bounded live-values fetch. ## Design History diff --git a/docs/FEATURES.md b/docs/FEATURES.md index daa2685..1d8f87b 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -7,7 +7,7 @@ - [ ] Install and run one or more nodes, referencing upstream binaries, per platform - [ ] Verify and monitor node health and earnings - [ ] Receive rewards to a non-custodial public wallet address (the node holds no key) and check balance -- [ ] Channel-independent version self-check (manifest on an Autonomi-controlled URL) +- [ ] Versioned releases and documented updates through each supported installation channel ## Should Have (V1) diff --git a/docs/SOURCE-MAP.md b/docs/SOURCE-MAP.md index cfc3f36..3c6e36c 100644 --- a/docs/SOURCE-MAP.md +++ b/docs/SOURCE-MAP.md @@ -1,6 +1,6 @@ # Source Map — Autonomi Operator Skill -> **Orientation only — not authoritative.** This map helps an agent *find where operator-relevant truth lives* in upstream code. It is **not** a fact source, and it must **not** be baked into or cited by `SKILL.md`. Authority and judgement live in two places: (1) **`SKILL.md` and its modules** — where the agent exercises judgement about what to say and how to say it; and (2) the **source-binding manifest** (ADR-0006) — where each specific claim is pinned to code (repo / file / symbol / commit). Use this map to know where to look; then read the code, apply judgement, and bind each claim in the manifest. The map can go stale — the code and the manifest cannot be skipped. +> **Orientation only — not authoritative.** This map helps an agent *find where operator-relevant truth lives* in upstream code. It is **not** a fact source, and it must **not** be baked into or cited by `SKILL.md`. Authority and judgement live in two places: (1) **`SKILL.md` and its modules** — where the agent exercises judgement about what to say and how to say it; and (2) the **source-binding manifest** (ADR-0006) — where each Autonomi-specific claim records upstream code provenance (repo / file / symbol / commit) or an explicit team-confirmed exception pending upstream source. Ordinary platform behaviour requires separate platform evidence before support is claimed. Use this map to know where to look; then read the code, apply judgement, and bind each Autonomi claim in the manifest. The map can go stale — the code and the manifest cannot be skipped. > > Scope is **operator** (run and use the network), not developer/build (ADR-0003): build surfaces route to the Developer skill. The `autonomi-*-docs` repos are secondary cross-checks only, never a binding target — their own READMEs state the upstream code is the implementation truth. Org enumerated 2026-06-18 — 20 repos in `WithAutonomi`. @@ -9,14 +9,14 @@ ### `ant-node` (Rust) — the node binary - **Public wallet address (non-custodial):** `--rewards-address`; `src/payment/wallet.rs` — node holds no key, only verifies inbound payments name the address. - **Node flags / behaviour:** `src/bin/ant-node/cli.rs` *(confirm exact path against the repo)*. -- **Releases:** ML-DSA-65 (FIPS-204) signatures + `SHA256SUMS` — verify before use. -- **Operating-procedure constants (later tiers):** IP/subnet diversity limits; storage auto-scales (no fixed per-node ceiling); close-group size (**read as both 5 and 7 — resolve against code before authoring runbooks**). +- **Releases:** upstream artifacts provide ML-DSA-65 (FIPS-204) signatures + `SHA256SUMS`; verification before use is the required target, but the current script install route does not perform it. +- **Operating-procedure constants:** IP/subnet diversity limits; storage auto-scales (no fixed per-node ceiling); close-group size (**resolved to 7 in the completed deep-source research; retain an exact manifest binding wherever generated content uses it**). ### `ant-client` (Rust) — the `ant` CLI + core + node-management daemon (the core operator surface) - **Command tree:** `ant-cli/src/cli.rs` (+ the node command module under `ant-cli/src/commands/`). **Confirm the Tier-1 command tree directly against this code** — the SPEC's tree currently leans on the dev-docs reference; the binding target is the CLI source. - **Node lifecycle:** `ant node add | start | stop | status | reset`; `ant node daemon start | stop | status | info` (the node-management daemon — this is the operator "daemon"). - **Install:** `install.sh` / `install.ps1` (repo root; `curl … | bash` / `irm … | iex`) or `cargo build --release --bin ant`. -- **No-key boundary:** `ant-cli/src/main.rs` `require_secret_key()` — `SECRET_KEY` is a private key; `ant wallet address | balance` derive from it, so they are **not** used on the no-key operate-and-earn path. (Balance-without-a-key is the open Tier-1 question.) +- **No-key boundary:** `ant-cli/src/main.rs` `require_secret_key()` — `SECRET_KEY` is a private key; `ant wallet address | balance` derive from it, so they are **not** used on the no-key operate-and-earn path. The resolved key-free balance path is the manifest-bound read-only ERC-20 `balanceOf(address)` call through the public Arbitrum RPC. ## Secondary / later-tier source — pointer, not a Tier-1 binding @@ -26,12 +26,12 @@ These are build dependencies the node/client/SDK link against. An operator agent never calls them; at most they are *provenance* for specific constants, only when a claim needs one. -- **`evmlib`** (Rust + Foundry: `src/`, `contracts/`, `abi/`) — the EVM library plus the Solidity payment-vault and ANT-token contracts. **Development, not an operator interface.** Operator relevance is **only** as the provenance for EVM constants (ANT token address, payment-vault address, Arbitrum network config) *if* a later-tier claim needs them (e.g. a read-only on-chain balance check). **Not needed for Tier-1; never a binding target for operator commands.** +- **`evmlib`** (Rust + Foundry: `src/`, `contracts/`, `abi/`) — the EVM library plus the Solidity payment-vault and ANT-token contracts. **Development, not an operator interface.** Tier-1 uses it only as provenance for the ANT token address, Arbitrum public RPC, and read-only `balanceOf(address)` path; it is never a binding target for operator commands. - **`ant-protocol`** (Rust) — wire-protocol crate; a library, reference only, no operator commands. ## Out of scope — named so the exclusion is deliberate -- **`ant-keygen`** — *verified*: a **release-signing** utility (ML-DSA-65 signing/verifying release binaries; context `ant-node-release-v1`). Not the EVM wallet, not custody, not an operator tool; only the scheme behind the release signatures the install step verifies. Does **not** change ADR-0004 (no EVM-wallet keygen/keystore upstream). +- **`ant-keygen`** — *verified*: a **release-signing** utility (ML-DSA-65 signing/verifying release binaries; context `ant-node-release-v1`). Not the EVM wallet, not custody, not an operator tool; it provides the scheme the future verified-install path must use, but the current script route does not verify signatures. Does **not** change ADR-0004 (no EVM-wallet keygen/keystore upstream). - **`ant-android`, `ant-swift`, `ant-sdk` language bindings** — developer/build surface → Developer skill. - **`saorsa-core`, `saorsa-transport`, `saorsa-pqc`, `saorsa-mls`, `ant-quic`, `saorsa-gossip`** — network/transport/crypto internals; the operator does not touch them. - **`ant-ui`** (GUI), **`self_encryption`**, **`ant-merkle`** (libraries), **`indelible`** (a Go consumer app). @@ -49,4 +49,4 @@ These are build dependencies the node/client/SDK link against. An operator agent ## Source-of-truth stance -The map is **orientation**. Binding authority is the **source-binding manifest** (ADR-0006): each claim pinned to code — repo / file / symbol / commit (`source_evidence`), with compatibility (`tested_with` / `requires_min` / `known_incompatible`) a separate axis (ADR-0009). Judgement about *what the skill says* lives in `SKILL.md`. Docs repos are secondary cross-checks. Re-verify the command tree against `ant-client` source during authoring rather than trusting the dev-docs mirror. +The map is **orientation**. Binding authority for Autonomi-specific claims is the **source-binding manifest** (ADR-0006): each such claim has upstream code provenance — repo / file / symbol / commit (`source_evidence`) — or an explicit team-confirmed exception with its accountable record, uncertainty, and revalidation path. Ordinary platform behaviour requires appropriate platform evidence outside the manifest before support is claimed. Compatibility (`tested_with` / `requires_min` / `known_incompatible`) is a separate axis (ADR-0009). Judgement about *what the skill says* lives in `SKILL.md`. Docs repos are secondary cross-checks. Re-verify the command tree against `ant-client` source during authoring rather than trusting the dev-docs mirror. diff --git a/docs/SPEC-tier1-operate-and-earn.md b/docs/SPEC-tier1-operate-and-earn.md index f2e7ec1..87d18d0 100644 --- a/docs/SPEC-tier1-operate-and-earn.md +++ b/docs/SPEC-tier1-operate-and-earn.md @@ -1,6 +1,6 @@ # SPEC — Tier 1: Operate and earn -> Bounded build slice for the Autonomi Operator Skill. Defines what Tier 1 must do, the acceptance bar, the source-bound command surface, and the verification plan. Scope is fixed by the team go-ahead (2026-Jun-18): **author and agent-test Tier 1 only**; ADR-0004 (custody) and ADR-0005 (gas) stay **Proposed** and are not touched. Aligns to DESIGN §2–§6 and §12 and the ROADMAP capability ladder. This is a spec (what the chunk must do), not a plan (order) or an ADR (invariant). +> **Historical build spec, not current implementation state.** This defines what Tier 1 must do, its acceptance bar, source-bound command surface, and verification plan. The current skill has not yet met every requirement here, notably verified delivery, correct and tested Windows guidance, and the full live end-to-end run; read `planning/HANDOFF.md` and `README.md` for current state. Scope was fixed by the team go-ahead (2026-Jun-18): **author and agent-test Tier 1 only**; ADR-0004 (custody) and ADR-0005 (gas) stay **Proposed** and are not touched. Aligns to DESIGN §2–§6 and §12 and the ROADMAP capability ladder. This is a spec (what the chunk must do), not a plan (order) or an ADR (invariant). ## Scope @@ -18,7 +18,7 @@ - The node is configured with a **public `--rewards-address` only**. - No claim that agent-owned custody or spending is available; the sourcing menu names "agent-created" as first-class for autonomous use but routes its custody substrate onward to Tier 2 (gated; ADR-0004 Proposed). - Detect-first, install-only-when-missing; mutate an existing `ant` / `ant-node` setup only within granted remit (ADR-0008, ADR-0009). -- Every command/flag/constant is source-bound (ADR-0006); no invented commands or fallbacks. +- Completion requires every Autonomi-specific command/flag/constant to have explicit provenance (normally an upstream source binding; any temporary team-confirmed exception is recorded and pending upstream authority) under ADR-0006. Ordinary shell/OS observation must be checked for each claimed platform; no invented commands or fallbacks. ## Command surface (source-bound; ant-client @ `84332e2d`, dev-docs verified 2026-06-10) diff --git a/docs/VISION.md b/docs/VISION.md index 8c9d9dc..81303d3 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -2,7 +2,7 @@ ## Purpose -An auto-updating, agent-facing skill that teaches an AI agent to **operate and use the Autonomi network** — starting with running and managing nodes, and expanding (via progressive disclosure) toward using the network as a whole: handling the ANT that nodes earn, storing and retrieving data, acquiring more ANT when needed, and — at the frontier — routing onward to building on Autonomi. +A keepable-current, agent-facing skill that teaches an AI agent to **operate and use the Autonomi network** — starting with running and managing nodes, and expanding (via progressive disclosure) toward using the network as a whole: handling the ANT that nodes earn, storing and retrieving data, acquiring more ANT when needed, and — at the frontier — routing onward to building on Autonomi. It is **one modular operator skill, not a suite**: a lean entry that routes by the agent's task to bundled modules and leans on external resources for depth (the x0x model). The **first pass** delivers the complete node-operate-and-earn story; the skill is designed to grow toward full-network utilisation by adding modules and routing, never by requiring a collection of installs. @@ -14,7 +14,7 @@ It is an **operator skill** — about *doing and using*, not *building* — deli 2. Teach the agent to **receive and handle the ANT it earns** — node operation is non-custodial by construction (the node holds no key); wallet-address sourcing is a neutral menu (supplied / provisioned / agent-created), with agent-created first-class for autonomous use via an out-of-context custody substrate (the private key never enters the agent context; a recovery path declared at creation); plus how earning works and how to check the balance. 3. Document, honestly, **how earned ANT is used to store data** on the real, current payment path (ANT plus native gas) — without inventing or assuming a gas-abstraction mechanism that does not exist upstream; surface the gas constraint as a known limitation and route to live docs for spend depth. 4. Be **expandable toward whole-network use** — using ANT, acquiring more when short, storing and retrieving data — through progressive disclosure by task routing, not through extra installs. -5. **Stay current automatically** — content derived from and source-bound to upstream, with an in-skill version self-check, structured so a future upstream-sweep can regenerate it. +5. **Stay current through the delivery system** — source-backed content derived from and bound to upstream, with visibly provisional team-confirmed exceptions recorded while they await upstream authority; structured so a future upstream-sweep can regenerate it, with updates delivered by each installation channel. 6. Be **widely distributed and easy to install** at x0x-level quality, passing security scans. ## Non-Goals @@ -30,7 +30,7 @@ It is an **operator skill** — about *doing and using*, not *building* — deli - **First pass:** a fresh agent, given only this skill, can explain why to run a node, check machine fit, install and run one and several nodes on the **live network**, monitor health, configure a non-custodial public wallet address, and check and secure earnings — without inventing commands — with clear onward pointers for using ANT (storing data) and acquiring more. - The skill grows by adding modules and routing, not new installs. -- Installed copies self-report staleness; content traces to upstream sources. +- Installation channels can discover and deliver new versions; Autonomi-specific content carries explicit provenance, normally upstream source bindings with visibly provisional team-confirmed exceptions where authority has not caught up. - Passes the security scan; structure and quality on par with the x0x skill. ## Target Users / Audience @@ -43,7 +43,7 @@ Primary: **AI agents as operators and decision-makers** — managing, configurin - **Node-first, whole-network-bound.** Start with the complete node story; grow toward using the network as a whole. - **x0x is the structural precedent and quality bar** — a proven pattern we draw on, not a dependency. - **Operate autonomously, spend under authority.** Running and optimising nodes is non-custodial and can be fully autonomous; spending real ANT is the gated money line. -- **Document reality; don't invent.** Everything is derived from and source-bound to upstream; route to live facts for volatile detail; never assert mechanisms that don't exist. +- **Document reality; don't invent.** Bind source-backed facts to upstream; record any temporary team-confirmed exception with accountable provenance and unresolved uncertainty while it awaits upstream authority; route to approved live facts for volatile detail; never assert mechanisms that don't exist. - **Equip judgment with a neutral menu.** At every choice point — how many nodes, which path to ANT, whether to spend — give the agent an accurate, useful, user-friendly, and reasonably neutral menu of options for its use case, plus the live means to assess them. The skill's purpose is to inform the agent's judgement, not to make the decision for it. - **Safety around funds.** Default to non-custodial; make irreversibility explicit; never put a key on a node or in the repo. - **Cooperative framing.** Running nodes helps secure the network's data; earning ANT is the means to use the network. diff --git a/docs/adr/ADR-0006-skill-content-source-bound-to-upstream.md b/docs/adr/ADR-0006-skill-content-source-bound-to-upstream.md index ee73094..175d026 100644 --- a/docs/adr/ADR-0006-skill-content-source-bound-to-upstream.md +++ b/docs/adr/ADR-0006-skill-content-source-bound-to-upstream.md @@ -6,15 +6,15 @@ - **Reviewers:** David Irvine - **Supersedes:** none - **Superseded by:** none -- **Related:** ADR-0002 (internal modularity); vault `spec/DECISIONS.md` (channel-independent version check + upstream-sweep) +- **Related:** ADR-0002 (internal modularity); ADR-0013 (channel-owned skill updates); vault `spec/DECISIONS.md` (freshness + upstream-sweep) ## Context -The Autonomi network is live (version 2) and actively developed: constants, commands, and tooling in the upstream repos change over time. The skill exists to give agents in the wild **current** best practice and working tools, so anything affected by an upstream change must reach the skill rapidly. To make that possible, the skill must be derived from the upstream repos and be keepable-current — later, automatically — by analysing changes in those repos, without a rewrite. The automation pipeline itself is out of scope now; the **structure** that makes it possible is not, because it is cheap to adopt up front and close to impossible to retrofit. +The Autonomi network is live (version 2) and actively developed: constants, commands, and tooling in the upstream repos change over time. The skill exists to give agents in the wild **current** best practice and working tools, so anything affected by an upstream change must reach the skill rapidly. To make that possible, source-backed content must be derived from the upstream repos and be keepable-current — later, automatically — by analysing changes in those repos, without a rewrite. Occasionally a team recommendation leads its authoritative upstream source; that exception still needs explicit, accountable provenance and must remain visibly provisional. The automation pipeline itself is out of scope now; the **structure** that makes it possible is not, because it is cheap to adopt up front and close to impossible to retrofit. ## Decision Drivers -- Everything in the skill should be derived from upstream, with provenance. +- Source-backed content should be derived from upstream; temporary team-confirmed exceptions should remain traceable and visibly pending upstream authority. - A future upstream-sweep should be a bolt-on, not a rewrite. - Prevent silent staleness and drift. - Distinguish facts that can be auto-extracted from judgement that cannot. @@ -27,20 +27,20 @@ The Autonomi network is live (version 2) and actively developed: constants, comm ## Decision -All skill content is **derived from upstream repos** and **structured so it can be kept current by mechanical analysis of upstream changes**. Concretely: +All factual skill content carries **explicit provenance** and is **structured so upstream-backed claims can be kept current by mechanical analysis of upstream changes**. Concretely: -- Every fact, flag, command, and constant is **source-bound** (repo / file / symbol / commit) via a source-binding manifest. +- Every Autonomi-specific fact, flag, command, constant, and install behaviour has a provenance entry in the source-binding manifest. The normal form is an upstream **source binding** (repo / file / symbol / commit). If a team-confirmed operational value temporarily leads upstream documentation, the manifest instead records the accountable confirmer or recorder, date and repository record, known uncertainty, and revalidation path, and labels it pending upstream source; it remains a visible, provisional exception rather than an invented upstream binding. Ordinary operating-system/shell observation commands are not Autonomi claims and do not bind to an Autonomi repository, but platform-specific behaviour still requires appropriate platform evidence rather than assumption. - **Volatile facts** (flags, constants, contract addresses, network names, versions) are isolated and **single-sourced** — demarcated, never duplicated, never scattered through prose. - Content is tagged **mechanically-derived** (a future sweep may auto-regenerate it) vs **judgement-derived** (a sweep only flags it for human/agent review when its underlying mechanics change). -- Per fact, a deliberate choice between **bake-with-pin** (regenerated by the sweep) and **fetch-live** (pulled at use-time so it cannot go stale). +- Per fact, a deliberate choice between **bake-with-pin** (regenerated by the sweep) and **fetch-live** only under a separately approved, bounded trust contract such as ADR-0013 mechanism 4. Without that contract, the fact stays bundled. Invariants: -- No skill claim without a provenance binding. +- No Autonomi-specific skill claim without a manifest provenance entry. Upstream code is the default authority; any temporary team-confirmed exception is explicit, accountable, uncertain where stated, and pending upstream source. Ordinary platform behaviour follows the separate platform-evidence rule above. - Volatile facts are single-sourced and demarcated. - The mechanical-vs-judgement split is explicit in the structure. -- Nothing is hand-asserted that cannot be traced to upstream. +- Nothing is hand-asserted without traceable authority; upstream gaps are labelled rather than disguised. - Source bindings are **documentation provenance, not runtime pins** (see ADR-0009): the manifest separates `source_evidence` (proves a claim) from `tested_with` / `requires_min` / `known_incompatible` (which express tool compatibility). A source-evidence commit is never a runtime version requirement. -- **Cross-repo freshness contract:** upstream repos that change operator-facing surfaces (commands, flags, daemon endpoints, config, install paths, APIs, or reward/payment behaviour) should open an issue/PR against the skill repo, or emit a release-note marker the skill's freshness check consumes — so the skill is kept current from both ends, not only by its own sweep (relates to ADR-0007 and ADR-0009). +- **Cross-repo freshness contract:** upstream repos that change operator-facing surfaces (commands, flags, daemon endpoints, config, install paths, APIs, or reward/payment behaviour) should open an issue/PR against the skill repo, or emit a release-note marker the regeneration pipeline consumes — so the skill is kept current from both ends, not only by its own sweep (relates to ADR-0007 and ADR-0009). - The automation pipeline is out of scope here; the regeneration-ready structure is mandatory. ## Consequences @@ -56,11 +56,11 @@ Invariants: ### Neutral / Operational -- Companion concerns — an in-skill version self-check and a manifest hosting URL — are tracked separately; the sweep itself is a later build. +- Companion concerns — versioned releases and install-channel update behaviour — are tracked separately in ADR-0013; the sweep itself is a later build. ## Validation -Every section carries a source binding that resolves to a real upstream location; a spot-check diffs a bound constant against its source. Review rejects un-sourced claims. (Future) the sweep flags changed bindings for regeneration or review. +Every Autonomi-specific factual section carries manifest provenance that resolves to a real upstream location or an explicit team-confirmed exception with its accountable record, uncertainty, and revalidation path; a spot-check diffs an upstream-bound constant against its source. Ordinary operating-system/shell behaviour is checked against appropriate platform evidence outside the Autonomi manifest. Review rejects claims with neither the form of authority appropriate to their class nor an explicit unresolved label. (Future) the sweep flags changed bindings for regeneration or review. ## Notes for AI-assisted work diff --git a/docs/adr/ADR-0008-skill-structure-and-distribution.md b/docs/adr/ADR-0008-skill-structure-and-distribution.md index 0af03a4..5f25c41 100644 --- a/docs/adr/ADR-0008-skill-structure-and-distribution.md +++ b/docs/adr/ADR-0008-skill-structure-and-distribution.md @@ -17,12 +17,12 @@ ADR-0002 fixes the skill's *shape* (one modular skill, progressively disclosed) - All an agent needs is the skill — a single, self-sufficient entry point. - Skill-led distribution (the x0x pattern): the skill installs/configures the existing tools, not a separate setup. - Progressive disclosure as the quality bar: lean entry → modules on demand → outward to deeper topics. -- The housekeeping of a high-quality, installable skill: accurate metadata, an install manifest, a version self-check, a sound security posture. +- The housekeeping of a high-quality, installable skill: accurate metadata, documented channel-compatible install/update routes, and a sound security posture. - Adopt a proven pattern (x0x as precedent) rather than invent one. ## Considered Options -1. **A bare instructions document** (no manifest, metadata, or self-check). Rejected: not a self-sufficient, installable, high-quality skill; would fail the quality bar and the security scan. +1. **A bare instructions document** (no metadata, install route, or update path). Rejected: not a self-sufficient, installable, high-quality skill; would fail the quality bar and the security scan. 2. **A skill plus separate manual setup of the tools.** Rejected: an agent should need nothing but the skill; separate setup is friction and a source of drift. 3. **An x0x-style skill**: self-sufficient entry, skill-led distribution of the existing CLI + daemon, progressive disclosure, and full metadata/housekeeping. Chosen. @@ -31,10 +31,10 @@ ADR-0002 fixes the skill's *shape* (one modular skill, progressively disclosed) The skill is structured and quality-gated following the same broad pattern as x0x — a self-contained, progressively disclosed skill — but justified by Autonomi's own requirements; **x0x is a precedent, not a dependency.** Invariants: - **Self-sufficiency / skill-led distribution:** installing the skill is all an agent needs. The skill bootstraps access to the **existing upstream tools** — it detects what is already present, installs the `ant` CLI (the node daemon is the same `ant` binary in daemon mode) only when missing, and upgrades or mutates an existing setup only for an explicit compatibility/security reason **and only within the agent's granted remit** (escalating otherwise), per ADR-0009. It adds no new tooling (per ADR-0003) and is the single jumping-off point from which the agent can go as deep as it needs. -- **Progressive-disclosure layering:** a lean entry (opener + task routing) → **bundled** modules/references loaded on demand for depth (data storage, the upstream repos, security, developer-level detail). Live docs and other skills are **further reading, not the depth mechanism** — the skill is bundled so it works on a fresh/offline host and stays version-locked (ADR-0006), per ADR-0002 and ADR-0003. -- **High-quality housekeeping:** accurate frontmatter/metadata (name, a triggering-tuned description, version, license, keywords); clear provenance/attribution (the team behind it, the upstream repos it draws on, links); an install manifest following x0x's `metadata.openclaw.install` pattern, referencing upstream release binaries with signature verification; and an in-skill version self-check (per ADR-0006). +- **Progressive-disclosure layering:** a lean entry (opener + task routing) → **bundled** modules/references loaded on demand for depth (data storage, the upstream repos, security, developer-level detail). Live docs and other skills are **further reading, not the depth mechanism** — after installation, the bundled guidance remains available without contacting live docs or a freshness service and stays version-locked (ADR-0006), per ADR-0002 and ADR-0003. +- **High-quality housekeeping:** accurate frontmatter/metadata (name, a triggering-tuned description, version, license, keywords); clear provenance/attribution (the team behind it, the upstream repos it draws on, links); an install manifest following x0x's `metadata.openclaw.install` pattern, referencing upstream release binaries with signature verification; and version metadata and release artifacts that each supported install channel can update (per ADR-0006 and ADR-0013). - **Channel-agnostic distribution (from the dedicated skills repository, ADR-0007).** The skill conforms to the shared Agent Skills spec (agentskills.io) and installs through multiple channels, none privileged — e.g. `skills.sh` (`npx skills add`, which fans out to many agents), OpenClaw/ClawHub (via the `metadata.openclaw.install` manifest), and native/direct install (a directory or git URL). Channel-specific install UX is illustrative, not the mechanism — e.g. `skills.sh` lists a repo's skills by name + description for selection, so the `description` is both trigger-tuned (agent) and chooser-facing (human), with `--skill ` the deterministic selector. -- **Only the skill bundle ships:** what installs is `SKILL.md` + the bundled `references/`; repo-side material (`docs/`, `docs/adr/`, `planning/`, `source-bindings/`) never ships (ADR-0007). +- **Only the skill bundle ships:** what installs is `SKILL.md` plus the bundled `references/`; repo-side material (`docs/`, `docs/adr/`, `planning/`, `source-bindings/`) never ships (ADR-0007). - **Verified, secure delivery and clean removal:** checksums and signatures for both the skill and the binaries it installs, confirmed before use and reported back to the agent; the security checks agents and distribution channels expect (declared behaviour matches actual, reviewed install script); and a documented, clean **uninstall** path (stop processes, remove binaries and state) — agents trust a skill more when they can cleanly reverse it. - **Quality bar:** structure, security posture (signed binaries, reviewed install script, passes the security scan), and clarity on par with x0x. @@ -49,7 +49,7 @@ The detailed structure — exact sections, module files, manifest schema — is ### Negative / Trade-offs -- More housekeeping to build and keep current (metadata, manifest, self-check) — mitigated by the source-binding of ADR-0006. +- More housekeeping to build and keep current (metadata and release/update compatibility) — mitigated by the source-binding of ADR-0006. ### Neutral / Operational diff --git a/docs/adr/ADR-0010-human-facing-language-register.md b/docs/adr/ADR-0010-human-facing-language-register.md index 9c6be84..8c3dbb1 100644 --- a/docs/adr/ADR-0010-human-facing-language-register.md +++ b/docs/adr/ADR-0010-human-facing-language-register.md @@ -6,18 +6,18 @@ - **Reviewers:** David Irvine - **Supersedes:** none - **Superseded by:** none -- **Related:** ADR-0002 (progressive disclosure), ADR-0003 (operator scope), ADR-0004 (non-custodial / risk-based escalation), ADR-0009 (remit-gated operation), VISION (audience & principles), DESIGN §13 (operator personas + translation map). +- **Related:** ADR-0002 (progressive disclosure), ADR-0003 (operator scope), ADR-0004 (non-custodial / risk-based escalation), ADR-0008 (mutations only within granted remit), ADR-0009 (independent lifecycle), ADR-0014 (autonomy input; no surfaced tiers; product-surface boundary), VISION (audience & principles), DESIGN §13 (operator personas + translation map). ## Context -The skill is authored **for an AI agent**, where technical precision is correct and necessary — `--rewards-address`, an EVM address on Arbitrum One, ANT as an ERC-20, a transaction fee, ML-DSA signatures. But the operator running through the skill spans a spectrum (a person directly; an agent acting for a human; a fully autonomous agent), and crypto/developer jargon and a pile of low-level decisions are unhelpful — even alienating — to an ordinary person (the same "scary path" concern behind ADR-0004). David's intent, which we share: the agent should **do most of the work itself** — using its intelligence, judgement, and granted remit — and **not burden the operator** with inner workings, crypto detail, or routine choices, escalating to a human only when genuinely needed; and when it does communicate, use plain (but not patronising) language, ready to explain and expand on request. Nothing currently defines this interaction model, so the first authoring pass risks both over-exposing mechanics and over-asking. (This is distinct from the internal terminology standardization — "public wallet address" — which governs our own docs; this ADR governs how the agent *relates to and talks to* the operator.) +The skill is authored **for an AI agent**, where technical precision is correct and necessary — `--rewards-address`, an EVM address on Arbitrum One, ANT as an ERC-20, a transaction fee, ML-DSA signatures. But the operator running through the skill spans a spectrum (a person directly; an agent acting for a human; a fully autonomous agent), and crypto/developer jargon and a pile of low-level decisions are unhelpful — even alienating — to an ordinary person (the same "scary path" concern behind ADR-0004). David's intent, which we share: the agent should **do most of the work itself** — using its intelligence, judgement, and granted remit — and **not burden the operator** with inner workings, crypto detail, or routine choices, escalating to a human only when genuinely needed; and when it does communicate, use plain (but not patronising) language, ready to explain and expand on request. Nothing currently defines this interaction model, so authoring risks both over-exposing mechanics and over-asking. (This is distinct from the internal terminology standardization — "public wallet address" — which governs our own docs; this ADR governs how the agent *relates to and talks to* the operator.) ## Decision Drivers - The product reaches ordinary people through agents; alienating language or decision-dumping defeats the purpose. - Do-the-work-by-default: leverage the agent's judgement; reserve the human's attention for what's genuinely theirs. - Progressive disclosure (ADR-0002) applies to vocabulary and to *how much* is surfaced, not just modules. -- Safety is not "burden": money / risk / authority decisions must still reach the human (ADR-0004/0009). +- Safety is not "burden": authority grants or widening must be explicitly granted by, or escalated to, the authorised principal/delegator; gates that existing decisions reserve for humans remain human (ADR-0004/0008/0013). - Accuracy must survive simplification — plain must not become wrong, and must not imply capabilities or safety that don't exist (ADR-0004/0005). ## Considered Options @@ -30,19 +30,21 @@ The skill is authored **for an AI agent**, where technical precision is correct The skill defines how the agent **relates to and talks to** the operator, in three parts. -**1. Division of labour & disclosure.** The agent **shoulders the inner workings and the routine operational decisions itself** — using its judgement and the remit it has been granted (ADR-0004/0009). It surfaces to the operator **outcomes** and **the decisions that are genuinely theirs**, and otherwise stays out of the way. "How much to reveal" = as little as needed for the operator to stay informed and in control of what actually matters to them. Crucially, *minimise burden* applies to **operational mechanics and jargon, not to authority**: spend, risk, recovery, and consent decisions are always surfaced — quietly handling routine ops is good; quietly making a money/risk decision is not. Escalation is **by exception**, on the risk-based triggers already defined (authority/spend beyond remit, balance over threshold, backup/recovery, no safe substrate, explicit opt-in) — never for routine work, and never gated on "do you understand crypto?". +**1. Division of labour & disclosure.** The agent **shoulders the inner workings and the routine operational decisions itself** — using its judgement and the remit it has been granted (ADR-0004/0008). It surfaces **outcomes** and **the decisions that are genuinely the authorised principal/delegator's**, and otherwise stays out of the way; reporting adapts to the available channel rather than requiring a present human. Crucially, *minimise burden* applies to **operational mechanics and jargon, not to authority** — where "authority" means **granting or widening an envelope**, not acting within one. **Granting or changing an authority envelope** (spend, risk, recovery, consent) must be explicit from an authorised principal/delegator or escalated to one, **never inferred**. **Acting within a granted envelope** needs **no per-action approval** (a granted spend-envelope authorises spend within it — ADR-0004/0008); a live-value delta that would expand consequential action beyond what the granted/bundled values authorised is **still gated**, never self-authorised (ADR-0013). This does not delegate human-only gates: ADR acceptance remains a human governance decision, and ADR-0013 requires human approval for a material live-value delta. Quietly handling routine ops within remit is good; quietly *widening* authority is not. Where the authorised decision-maker **cannot be reached**, the agent **halts/defers** rather than proceeding on assumed authority. Escalation is **by exception**, on the risk-based triggers already defined (authority/spend beyond remit, balance over threshold, backup/recovery, no safe substrate, explicit opt-in) — never for routine work, and never gated on "do you understand crypto?". -**2. Persona-aware.** The operator is one of three personas (defined in DESIGN §13): a **human** operating directly, an **agent acting as a human's proxy**, or a **fully autonomous agent**. The agent adapts disclosure and register to which it is serving — full plain-language translation for a human; minimal-but-sufficient surfacing by a proxy agent to its principal; internal precision plus audit/escalation-only for a fully autonomous agent (which, absent a human, halts/defers at a gate rather than crossing it). +**2. Persona-aware.** The operator is one of three personas (defined in DESIGN §13): a person in hands-on **steered** operation (agent-assisted, still chat/text-driven), an **agent acting as a human's proxy**, or a **fully autonomous agent**. The agent adapts disclosure and register to which it is serving — full plain-language translation for a human; minimal-but-sufficient surfacing by a proxy agent to its principal; internal precision plus audit/escalation-only for a fully autonomous agent (which, when an authorised decision-maker is unreachable, halts/defers at a gate rather than crossing it). These personas shape *disclosure*, not authority; **ADR-0014** governs that the agent does not **self-classify** into them as autonomy tiers and that the safety line stays universal and mode-free. -**3. Plain-language register.** When addressing a human, the agent uses plain language — **assume intelligence, not knowledge** (plain, not patronising) — leads with meaning before naming a precise term, reports outcomes rather than commands/flags/hashes, keeps network/crypto internals out of view unless asked, and is **always ready to explain and expand on request** (progressive depth). A translation layer (technical → human; e.g. "a transaction fee for the payment", not "native Arbitrum gas") lives in DESIGN §13 and is applied across all human-facing copy. Accuracy is never sacrificed for simplicity. +**3. Plain-language register.** When addressing a human, the agent uses plain language — **assume intelligence, not knowledge** (plain, not patronising) — leads with meaning before naming a precise term, reports outcomes rather than commands/flags/hashes, keeps network/crypto internals out of view unless asked, and is **always ready to explain and expand on request** (progressive depth). A translation layer (technical → human; e.g. "a transaction fee for the payment", not "native Arbitrum gas") lives in DESIGN §13 and is applied across all human-facing copy. Accuracy is never sacrificed for simplicity. The register runs in **two directions** — precise for the agent, translated for the human — and the translation is applied **by judgement, illustratively, never as a literal find-and-replace** of terms. *(The clean product-surface / no-internal-vocabulary boundary is ADR-0014.)* Invariants: - **Do the work; escalate by exception.** The agent handles routine operation and decisions within its remit; it does not narrate machinery or hand the operator routine choices. -- **Never hide authority.** Money, risk, recovery, and consent decisions are always surfaced to the human, regardless of how light the rest of the disclosure is. +- **Authority is granted, not assumed.** A decision that **grants or widens** an envelope (spend, risk, recovery, consent) must come explicitly from an authorised principal/delegator or be escalated to one, never inferred. Acting **within** a granted envelope needs no per-action approval; an **unreachable** authority gate means **halt/defer**, not proceed. Gates reserved for humans by governance or another decision remain human. +- **Reporting adapts to the channel.** Full translation for a present human; minimal-but-sufficient for a proxy's principal; an audit trail for an autonomous agent. Absence of a reporting channel constrains *reporting*, not *authority* — an unreachable gate is deferred, not crossed. - **Plain, not patronising.** Human-facing language assumes intelligence, not specialist knowledge; precise terms are available, introduced in plain words first, and explained on request. - **Outcomes, not mechanics.** No CLI tables, flags, hashes, or raw addresses in human-facing output unless asked. - **Accuracy over simplicity.** Simplification never makes a claim wrong or implies a capability/safety property that doesn't exist. +- **Translate by judgement, not by rote.** The human-facing register is applied illustratively for each operator — never a literal find-and-replace of terms. - The translation map and personas live in DESIGN §13; exact word choices are a product/UX decision owned by Jim. ## Consequences @@ -56,16 +58,23 @@ Invariants: ### Negative / Trade-offs - Authors maintain a register and a translation map, and must judge the do-vs-surface line — more care per claim. -- A risk of over-simplifying into inaccuracy, or of under-surfacing a decision that *was* the human's — mitigated by the "never hide authority" and "accuracy over simplicity" invariants and the review gauntlet. +- A risk of over-simplifying into inaccuracy, or of under-surfacing a decision that *was* the human's — mitigated by the "authority is granted, not assumed" and "accuracy over simplicity" invariants and the review gauntlet. ### Neutral / Operational -- Builds on ADR-0004's risk-based escalation and ADR-0009's remit; this ADR is their UX expression, not a new escalation policy. +- Builds on ADR-0004's risk-based escalation and ADR-0008's within-remit mutation; this ADR is their UX expression, not a new escalation policy. - The internal "public wallet address" standardization is the agent-facing precision layer; the human-facing layer translates further. ## Validation -A reading of the agent's human-facing output finds it plain and non-patronising, with no unexplained crypto/developer jargon and no raw mechanics; the agent is shown to handle routine work without surfacing it, yet to surface money/risk/authority decisions every time; it explains/expands correctly on request; and simplification introduces no inaccuracy. The clean-context and adversarial gauntlet includes this read (over-exposure, over-asking, jargon, and any hidden authority decision are findings). +A reading of the agent's human-facing output shows: + +- it is plain and non-patronising, with no unexplained crypto/developer jargon and no raw mechanics; +- routine work **within remit** is handled without surfacing it; +- any **grant or change of authority** (spend/risk/recovery/consent) comes explicitly from an authorised principal/delegator or is escalated, never inferred, while acting **within a granted envelope** proceeds without per-action approval; reporting adapts to the channel; an **unreachable gate is deferred**, not crossed; and human-only gates remain human; +- it explains/expands correctly on request, and simplification introduces no inaccuracy. + +The clean-context and adversarial gauntlet includes this read (over-exposure, over-asking, jargon, and any inferred/assumed authority are findings). ## Notes for AI-assisted work diff --git a/docs/adr/ADR-0011-health-observability-query-based.md b/docs/adr/ADR-0011-health-observability-query-based.md index 92f2007..00795c2 100644 --- a/docs/adr/ADR-0011-health-observability-query-based.md +++ b/docs/adr/ADR-0011-health-observability-query-based.md @@ -6,7 +6,7 @@ - **Reviewers:** David Irvine - **Supersedes:** none - **Superseded by:** none -- **Related:** ADR-0006 (source-bound; no invented/brittle surface), ADR-0009 (detect-first / non-mutating), ADR-0004 (non-custodial), DESIGN §5 (interface model), §9 (operating boundary), §12 (capability ladder); the operate-and-earn SOP; the upstream "CLI health commands" thread. +- **Related:** ADR-0006 (source-bound; no invented/brittle surface), ADR-0009 (detect-first / non-mutating), ADR-0004 (non-custodial), ADR-0014 (uncertain-remit default), DESIGN §5 (interface model), §9 (operating boundary), §12 (capability ladder); the operate-and-earn SOP; the upstream "CLI health commands" thread. ## Context @@ -50,7 +50,7 @@ Invariants: - **No log-scraping for health.** Logging stays off by default; debugging-only; never a health data source. - **No coupling to node internals** (log strings or on-disk file layout) for health signals. - **Work within supported interfaces.** Health depth grows when supported queries exist — not by reaching into internals. -- **Host metrics via the OS are always permitted** — host stewardship needs them, and they are not Autonomi internals. +- **Host metrics via the OS are observational, not blanket authority.** They may be read when needed to establish state or steward the host within granted remit; under missing, ambiguous, or exceeded remit, ADR-0014 limits this to necessary non-mutating observation. - **Reduced mode is honest:** the skill states what it cannot currently observe rather than inferring it unreliably. ## Consequences diff --git a/docs/adr/ADR-0013-skill-freshness-and-channel-owned-updates.md b/docs/adr/ADR-0013-skill-freshness-and-channel-owned-updates.md new file mode 100644 index 0000000..ba80035 --- /dev/null +++ b/docs/adr/ADR-0013-skill-freshness-and-channel-owned-updates.md @@ -0,0 +1,105 @@ +# ADR-0013: Skill freshness and channel-owned updates + +- **Status:** Proposed +- **Date:** 2026-07-13 +- **Decision owners:** Jim Collinson +- **Reviewers:** David Irvine, Hermes +- **Supersedes:** none +- **Superseded by:** none +- **Related:** ADR-0006 (source-bound; mechanical-vs-judgement review split), ADR-0008 (channel-agnostic distribution), ADR-0009 (independent lifecycle); `planning/channel-update-research.md`; `planning/NEXT-PHASE.md` §3 & §5; `planning/node-resource-spec-brief.md`; `planning/REBUILD-BRIEF.md` (freshness / source-bindings section) + +## Context + +The shipped skill is a **bundled, versioned snapshot** — `SKILL.md` plus bundled `references/` — deliberately self-contained so its guidance can be loaded and used without contacting an update or freshness service (ADR-0008). Source-backed facts are bound to upstream code; any temporary team-confirmed value that leads upstream is explicitly labelled pending source (ADR-0006). Autonomi operations still require whatever network access their task normally needs. + +A snapshot drifts from reality along **independent axes**: the underlying `ant` tool updates on its own lifecycle; the skill's own instructions get revised; and a *narrow subset* of the operational figures it carries (resource sizing, shunning/standing thresholds) change faster than the whole skill is re-released. Distribution is channel-agnostic (ADR-0008), but every installed copy still arrived through a channel with its own update semantics. Runtime fetching solely to check the skill's own version duplicates that layer while adding latency, failure, and an instruction/injection surface. + +This ADR sets out how the skill stays current across those axes without sacrificing bundle availability when freshness services are unavailable, source-binding, or trust — by treating them as separate mechanisms rather than one. + +Research recorded in `planning/channel-update-research.md` found no ordinary first-party `SKILL.md` that checked its own version on load. Installed-skill freshness was owned by marketplaces, installers, or a product CLI; live fetching inside skills was reserved for task-specific documentation and data. This ADR adopts that model. Mechanism 3 has no runtime self-check; mechanism 4 retains the separately bounded, data-only runtime design for a narrow class of volatile operational values. + +## Decision Drivers + +- Multiple distribution channels, each with an update mechanism or an explicit manual-reinstall contract. +- No freshness-service dependency (ADR-0008) — load and use the bundled guidance without contacting an update or live-values endpoint. +- Source-bound discipline (ADR-0006) — source-backed facts bind to upstream code, temporary team-confirmed exceptions are explicit and pending source, regeneration follows the manifest, and the mechanical-vs-judgement review split remains clear. +- A narrow set of operational values changes faster than whole-artifact releases. +- Trust/security — a runtime fetch must not let unverified content steer the agent; live material must be typed *data*, not free-form instructions. +- Don't pester; degrade gracefully — freshness failure never blocks access to bundled guidance or nags, but stale values must not authorise a first deployment or new consequential scaling. + +## Considered Options + +1. **Let each install channel own installed-skill updates, while handling other kinds of drift separately.** Chosen: this uses each channel's established delivery mechanism and keeps update code out of the instructions it replaces. +2. **Bundle everything; refresh only via full re-releases.** Rejected as a complete freshness model: releases are right for skill prose, but cannot keep fast-moving operational values current between releases. +3. **Fetch a published skill version whenever the skill is first used.** Rejected: duplicates install-channel update discovery, adds a network request to ordinary skill loading, and exposes remote input to the agent for no task-specific benefit. +4. **Live-fetch everything at runtime (no bundling).** Rejected: creates a hard freshness-service dependency, maximises the trust surface, and would fetch judgement-derived prose — unsafe to inject. +5. **Make install-manager identity and folder hashes a contract implemented by the skill.** Rejected: managers may use those mechanisms internally, but reproducing them in the skill would be channel-specific machinery without a clear user benefit. + +## Decision + +Skill freshness is handled as **four distinct mechanisms**, each with its own lifecycle. + +**1. Tool & binary updates — documented, source-bound context (not a skill mechanism).** +The `ant` tool and its binaries update on their own lifecycle (auto-upgrade channel; installer fetches the latest; ADR-0009). The skill does not manage this; it **documents** the behaviour so the agent operates with correct expectations, and every such fact is **source-bound** (ADR-0006). This is context the other mechanisms depend on — when upstream update behaviour changes, that change enters the skill through mechanism 2, never by drift. + +**2. Producing skill versions — reviewed, source-bound regeneration.** +Automation watches upstream against the source-bindings manifest and regenerates the artifact, respecting **ADR-0006's split**: **mechanical, source-bound content** (commands, flags, figures) may be regenerated automatically, while **judgement-derived content** (doctrine, prose, guidance) is **flagged for human review**, never silently rewritten. A regenerated candidate passes a **reviewed release/promotion gate** before it is published as a new versioned snapshot. Regeneration is from the manifest — not hand-patching to chase upstream. + +**3. Consuming skill updates — the installation channel owns delivery.** +Every released skill carries synchronized version metadata across the surfaces used by its supported channels. The installed skill makes no network request solely to check its own version and does not inspect install-manager state or modify its own files. + +The channel that installed a copy owns update discovery and delivery through its documented mechanism. A manually copied bundle is explicitly non-updating and is replaced by repeating the installation. A copy installed from a content-addressed commit SHA or a release identifier whose channel enforces immutability remains pinned unless the person deliberately chooses a newer source. Merely recording a `ref` does not make it immutable: a branch moves, and a tag is a pin only where source/channel governance prevents it from being moved. Channel-specific commands, metadata, and reload behaviour belong in source-bound implementation documentation, not this decision record. + +**4. Volatile-value freshness — a deferred, bounded, data-only, best-effort live check.** +A narrow class of operational **values** (resource figures, shunning/standing thresholds) changes faster than the artifact is re-released. If this deferred mechanism is implemented, the skill MAY consult a single authoritative source at runtime. The fetch is **non-mutating observation**, but that does **not** itself grant network/egress authority: the bounded call runs only within affirmative network/egress remit. If that remit is missing or ambiguous, the agent skips the fetch and uses the bundled values. Even when authorised, the call is limited to the one authoritative source — never an open egress right. It runs under strict bounds: + +- **Data-only, typed.** Only the structured, machine-readable **values block** is fetched (the parameters specified in `planning/node-resource-spec-brief.md`, once published as the Recommended Node Resource Document) — schema-typed numbers with units, never free-form prose. **Judgement-derived guidance/principles are never fetched**; they remain reviewed bundle content. (This mirrors the two-register split in the resource brief: *values* are source-bound data; *principles* are bundled doctrine.) +- **Trust protocol — not merely "pinned."** The check requires: a **signed, versioned envelope**; a **bundled trust root** (the publisher's public key shipped in the skill); a **canonical encoding and fixed schema**; **key rotation and revocation valid only when chained to the currently-trusted bundled root (or delivered by a reviewed bundle re-release)** — an unanchored rotation/revocation asserted over the runtime channel is rejected; **monotonic ordering and an expiry** (reject anything older than what's installed, or expired); **replay/downgrade rejection**; **authorised rollback only** — a rollback is a *forward*, higher-sequence signed instruction that lowers a value, never acceptance of an older/lower-sequence envelope (which stays rejected as a downgrade); and explicit handling of **malformed, unverifiable, or conflicting** responses (treat as *unavailable* → fall back to the bundle). +- **Best-effort and bundle-backed.** Reachable and verified → the value informs **observation and reporting**, and reaches behaviour only through the apply policy below. Unreachable, unverifiable, expired, or conflicting → **fall back to the bundled, team-confirmed values**. This is conservative continuity from the last reviewed baseline, not a guarantee that unresolved or stale values remain operationally current; **prolonged** unreachability is itself an escalation trigger. +- **Apply policy — default-material, fail-safe.** A verified live value does **not** silently change behaviour. **Every verified live delta is treated as material and gated unless it matches a fixed, bundled allowlist of cosmetic values** — materiality is default-on, not a denylist of named thresholds. Materiality is judged **against the reviewed, team-confirmed bundled baseline** (never against the last-applied live value, so a source cannot walk a safety value across the line in sub-threshold steps), and the **materiality criteria are themselves bundled and reviewed, never read from the fetched payload** (so a source cannot declare its own change immaterial). **Applying a material change** — anything that would authorise or expand consequential action (adding/removing nodes, moving data, changing node count or placement, crossing the disk/spread thresholds) — **requires human approval**; absent a human, the agent **defers the consequential action** and continues existing operation on bundled values. This gate holds **even inside a granted operational envelope**: a granted envelope authorises action computed from approved/bundled values, but a live delta that would expand consequential action beyond what those values authorised is still gated — verified-source is never self-authorising (reconciles ADR-0010's within-envelope autonomy). A verified **immaterial** value informs **monitoring and reporting only** and never becomes the basis of a consequential computation until approved. Once mechanism 4 exists and bundled values carry a declared maximum age, **stale bundled values** may sustain existing operation but do not authorise a first deployment or new consequential scaling; those actions wait for fresh verified values. + +Checks run at **meaningful moments** (session start; before a consequential resource/scaling decision), not on every action, and surface only what is genuinely the human's to decide. + +Invariants: +- **No freshness-service dependency.** The skill loads and provides bundled guidance without contacting an update or live-values endpoint; operational tasks may still require their normal network access. Mechanism 3 is external to skill execution and mechanism 4 is best-effort, never a hard dependency for access to the guidance. +- **Source-bound, reviewed regeneration.** Source-backed facts bind to upstream and temporary team-confirmed exceptions remain explicit and pending upstream authority (ADR-0006); mechanical content may auto-regenerate, judgement-derived content is flagged for review, and a reviewed gate precedes any release. +- **Installed-skill updates are channel-owned** (mechanism 3); the skill performs no self-version fetch, managers use their native version/source records, manual copies state that they do not auto-update, and only a content-addressed commit SHA or channel-enforced immutable release identifier counts as a pin. Branches and other mutable refs follow the channel's update semantics. +- **Live material is typed data, never prose** (mechanism 4); judgement guidance stays bundled and reviewed. +- **Verified-source ≠ authorised-to-act.** A material live delta needs human approval — **even inside a granted envelope**; absent a human, defer the consequential action. Once mechanism 4 defines staleness, stale bundled values may sustain existing operation but never authorise a first deployment or new scaling. +- **Trust is explicit** (mechanism 4): signed/versioned envelope, bundled trust root, **root rotation/revocation only when chained to the bundled root**, schema, monotonic ordering/expiry, replay/downgrade rejection, forward-only authorised rollback, defined failure handling. +- **No pestering.** Checks run at meaningful moments and surface only genuinely-human decisions. + +Mechanism 4 requires an authoritative *Recommended Node Resource Document* (specified by `planning/node-resource-spec-brief.md`, which currently lists the parameters it must quantify but is not yet a fetchable values block) and a detailed protocol/spec before implementation. This ADR fixes the model, trust and apply requirements, and invariants; the protocol/spec must fix mechanism 4's wire details before it is built. + +## Consequences + +### Positive + +- Four mechanisms that can be built, reasoned about, and secured independently. +- Installed-skill update discovery and delivery use established channel machinery rather than a second mechanism embedded in the skill. +- A narrow set of values can update without re-shipping the artifact; structural change goes through the reviewed regenerate/release path. +- Bundled guidance remains available when an update or live-values service is unavailable. +- The runtime trust boundary is explicit and data-only, and "verified" is cleanly separated from "authorised to act." + +### Negative / Trade-offs + +- Mechanism 4 is a real security surface — it needs a genuine signing/verification protocol and careful failure handling; it is deliberately constrained (data-only, materiality-gated, bundle-backed) but non-trivial to build correctly. +- Mechanism 2 is engineering plus an ongoing review gate. +- Mechanism 4 is blocked on the authoritative values document existing and being published under the trust protocol. +- Manually copied skills have no automatic update notification, and some channels require the user to enable or request updates explicitly. + +### Neutral / Operational + +- Ties to NEXT-PHASE §3 (mechanism 2), supported installation channels (mechanism 3), and the node-resource SOP (mechanism 4's source). Implementation progress belongs in planning, not this decision record. + +## Validation + +- The skill loads and provides its bundled guidance without contacting an update or live-values endpoint; no network request is made solely to check the installed skill's version. Tests do not misrepresent network-dependent Autonomi operations as offline. +- **Mechanism 3:** each supported managed channel can update a released test copy through its documented operation; a manual copy is documented as non-updating; a commit SHA or channel-enforced immutable release identifier remains fixed; a moving branch advances only through the channel's documented update operation; and a tag is treated as a pin only when its immutability is enforced rather than assumed. The skill does not inspect manager state or modify itself. +- **Mechanism 4:** without affirmative network/egress remit, no fetch occurs and the bundled values are used; when authorised, only typed values are fetched (never prose); a malformed / unsigned / expired / downgraded / conflicting response, and any unanchored trust-root rotation, is rejected and falls back to the bundle; **every delta is gated as material unless on the bundled cosmetic allowlist**, materiality is judged against the bundled baseline using bundled criteria, and a material delta is never applied without human approval **even inside a granted envelope** — absent a human the consequential action is deferred while existing operation continues on bundled values. +- **Stale-values boundary:** once mechanism 4 defines a maximum age, an expired bundled baseline may sustain existing operation but cannot authorise a first deployment or new consequential scaling; those actions wait for fresh verified values. +- **Mechanism 2:** mechanical regeneration is automatic; judgement-derived changes are flagged for review; nothing releases without passing the review gate. + +## Notes for AI-assisted work + +AI tools may help draft this ADR, but **must not mark it Accepted without human review**. Accepted ADRs are immutable: create a new superseding ADR rather than editing an Accepted ADR. diff --git a/docs/adr/ADR-0014-autonomy-input-and-product-surface.md b/docs/adr/ADR-0014-autonomy-input-and-product-surface.md new file mode 100644 index 0000000..ef22048 --- /dev/null +++ b/docs/adr/ADR-0014-autonomy-input-and-product-surface.md @@ -0,0 +1,80 @@ +# ADR-0014: Autonomy is an input, not a mode — default-deny remit, and a clean product surface + +- **Status:** Proposed +- **Date:** 2026-07-13 +- **Decision owners:** Jim Collinson +- **Reviewers:** David Irvine, Hermes +- **Supersedes:** none +- **Superseded by:** none +- **Related:** ADR-0002 (single holistic skill), ADR-0003 (operator scope), ADR-0004 (non-custodial / least privilege), ADR-0008 (mutations only within granted remit), ADR-0009 (independent lifecycle), ADR-0010 (human interaction model & register), ADR-0012 (product-first naming), DESIGN §13 (operator personas), `planning/REBUILD-BRIEF.md` §10. + +## Context + +The skill serves operators across an autonomy spectrum (a person in hands-on steered operation; an agent acting as a human's proxy; a fully autonomous agent — DESIGN §13, ADR-0010). Two tempting patterns would harm the skill, and a third gap needs closing: + +- **Self-classified autonomy tiers.** It is tempting to have the skill instruct the agent to *classify itself* into an autonomy "tier"/"mode" and branch its behaviour on that. But the agent's autonomy is **already an input** it holds from its human/harness — self-classification is redundant, error-prone, and dangerous: a mis-selected tier could weaken the safety line that must hold regardless of autonomy. +- **Internal vocabulary leaking into the product.** The skill is designed using internal/build vocabulary — tiers, personas, "operator", "engine", "gauntlet", "packet", "source-binding", ADR/spec references. If that language leaks into the shipped, product-facing text, it mislabels and clutters the product (related to the naming decision, ADR-0012, and the register decision, ADR-0010). +- **No defined behaviour under uncertain remit.** ADR-0004/0009 gate custody/spend/authority, but nothing defines what the agent does *by default* when remit is **missing, ambiguous, or exceeded** — and that default must not depend on a self-selected mode. + +## Decision Drivers + +- The non-custodial safety line (ADR-0004) must hold **independent of autonomy** — no tier may weaken it. +- Self-classification is redundant (autonomy is an input) and a new error surface. +- The shipped product must read as a clean, self-contained product (ADR-0010/0012), not as build scaffolding. +- Uncertainty needs a **safe, predictable default** that doesn't rely on a mode. +- Safety/reversibility is **not** authority — mutation needs granted remit (ADR-0004 / 0008 / 0009). + +## Considered Options + +1. **Surface autonomy tiers the agent self-selects, and branch behaviour per tier.** Rejected: redundant (autonomy is an input), error-prone, and risks a weaker safety path on a mis-selected tier. +2. **Leave autonomy handling and the uncertain-remit default implicit/undefined.** Rejected: no defined behaviour under ambiguous remit invites over-reach, and leaves the product-surface vocabulary boundary unstated. +3. **Autonomy is an input (no surfaced tiers); a mode-free default-deny under uncertain remit; and an explicit no-internal-vocabulary product-surface boundary.** Chosen. + +## Decision + +**1. Autonomy is an input — no surfaced tiers, no self-classification.** The skill does not ask the agent to classify itself into an autonomy mode; its autonomy is an input it already holds from its human/harness. Personas (DESIGN §13) are a **design lens** — for authoring, and for adapting *disclosure* (ADR-0010) — **not a runtime tiering** the agent selects; behaviour and safety never branch on a self-declared tier. The non-custodial safety line (ADR-0004) is **universal and mode-free**. + +**2. Mode-free default-deny under uncertain remit — deny *mutation*, not necessary observation.** Safety and reversibility are **not** authority. When remit is missing, ambiguous, or exceeded, the agent may perform only the **necessary non-mutating observation** needed to establish state and authority. Regardless of persona: + +- **Missing or ambiguous remit** → the agent limits itself to the **non-mutating observation** needed to establish state and authority (e.g. read-only status/balance checks), and otherwise **asks / escalates / defers**. It does **not** mutate to "fill" the gap, even reversibly. +- **Exceeded remit** → it does **not** perform the proposed action; it remains limited to necessary non-mutating observation, then asks / escalates / defers. +- **Any consequential or state-changing action** (install/upgrade, start/stop, delete/reset, volume selection, spend) → requires **affirmative remit**; absent that, ask / escalate / defer. +- **Emergency containment** is **not** a self-declarable licence. No emergency-mutation authority exists by default: any such authority would have to be **separately and explicitly defined and granted** (narrowly bounded), and **until it is, the capability is inert** — the agent must not assume it, and "emergency" is never self-declared to justify a mutation. + +This makes explicit and mode-independent the remit-gating of ADR-0004 / 0008 / 0009: mutate only within granted remit; escalate rather than mutate outside it. + +**3. A clean product surface — no internal vocabulary.** The **product surface** — everything shipped/installed: `SKILL.md` and `references/` — carries **none of the internal/build/process vocabulary** used to design the skill. The forbidden set (illustrative, not exhaustive): "tier", "persona", "operator" as a label, "engine", "capture evidence", "gauntlet", "packet", "source-binding" as user-facing jargon, ADR/spec/PR references, TODO / process markers, and internal mode names. Repo-side material (`docs/`, `docs/adr/`, `planning/`, `source-bindings/`) is **exempt** — it is not shipped. + +Invariants: +- **Autonomy is an input; the skill never makes the agent self-classify into a tier.** +- **The non-custodial safety line is universal and mode-free** — no autonomy level relaxes it. +- **Default-deny is deny-*mutation*, not necessary observation.** Missing, ambiguous, or exceeded remit permits only necessary non-mutating observation to establish state and authority, followed by asking/escalating/deferring; any state-changing action needs **affirmative remit**. Safety/reversibility never substitutes for authority (ADR-0004 / 0008 / 0009). +- **No internal/build vocabulary in the shipped product surface** (`SKILL.md` + `references/`); repo-side docs are exempt. + +## Consequences + +### Positive + +- Safety behaviour is coherent across all three personas with **no branching on a self-declared tier** and no mis-classification risk. +- A predictable, safe default under uncertain remit. +- The shipped product reads cleanly, matching the naming and register decisions (ADR-0010/0012). + +### Negative / Trade-offs + +- Default-deny occasionally asks/defers where a bolder agent would act — an accepted cost given the non-custodial safety posture (ADR-0004). +- Authors must actively police the product-surface vocabulary boundary. + +### Neutral / Operational + +- Refines ADR-0010's persona-awareness (personas adapt *disclosure*, not *authority*) and complements ADR-0012 (product-first naming). +- Builds on ADR-0004 (non-custodial) and ADR-0009 (remit) as their behavioural default, not a new escalation policy. + +## Validation + +- **Personas without self-classification:** exercised as all three personas, the skill never prompts the agent to declare a tier; the **authority/safety gates are identical** across them, while **disclosure and escalation *routing* are appropriate to the supplied context** — a present human, a proxy's principal, or an autonomous agent's asynchronous/deferred path (ADR-0010) — never keyed on a self-declared tier. +- **Uncertain-remit default, by action class:** with missing/ambiguous/exceeded remit, **only necessary read-only observation is allowed** to establish state and authority, including status/balance and host/resource checks when relevant; **install/upgrade, start/stop, delete/reset, external-volume selection, and spend are not performed without affirmative remit** — the agent asks/escalates/defers. Reversibility does not authorise a mutation. +- **Product-surface boundary:** the shipped `SKILL.md` + `references/` contain none of the forbidden build/process vocabulary (a lint/grep + adversarial read); repo-side docs are not checked. + +## Notes for AI-assisted work + +AI tools may help draft this ADR, but **must not mark it Accepted without human review**. Accepted ADRs are immutable: create a new superseding ADR rather than editing an Accepted ADR. diff --git a/docs/operating-doctrine.md b/docs/operating-doctrine.md index 53ed5b5..43beffd 100644 --- a/docs/operating-doctrine.md +++ b/docs/operating-doctrine.md @@ -1,6 +1,6 @@ # Autonomous Operating Doctrine — the engine -> What the **fully-autonomous agent** does by default — operating autonomously toward a delegated objective, with **no human engaged in the operational loop** (a human usually set the objective and owns it, but isn't present for the running of it). This is the shared base; the **human-proxy** and **steered** personas layer disclosure and control on top (the concentric model — §8). Grounded in the deep source research (rewards, storage, topology, daemon/observability) and ADR-0004/0005/0006/0009/0010/0011. Observability is query-based per ADR-0011. Feeds the skill's `references/operating-procedures.md` and `references/agent-autonomy-policy.md`. +> What the **fully-autonomous agent** does by default — operating autonomously toward a delegated objective, with **no human engaged in the operational loop** (a human usually set the objective and owns it, but isn't present for the running of it). This is the shared base; the **human-proxy** and **steered** personas layer disclosure and control on top (the concentric model — §8). Grounded in the deep source research (rewards, storage, topology, daemon/observability) and ADR-0004/0005/0006/0009/0010/0011/0014. Observability is query-based per ADR-0011. Feeds the skill's `references/operating-procedures.md` and `references/agent-autonomy-policy.md`. ## 1. Objective — what it optimises for @@ -49,7 +49,7 @@ A fully-autonomous agent **escalates asynchronously to whoever delegated the obj - the host reclaiming resources (back off / shed); - no safe substrate for a spend-shaped goal (defer that goal). -It records just enough context **at the point of an escalation** for a human to pick up — not a standing log. When it can't observe enough to decide safely, it chooses the smaller, reversible action. +It records just enough context **at the point of an escalation** for a human to pick up — not a standing log. When it can't observe enough to decide safely, it performs only the necessary non-mutating observation needed to establish state and authority, then asks, escalates, or defers. Reversibility does not grant authority to mutate. ## 8. What the personas layer on top diff --git a/docs/skill-grounding.md b/docs/skill-grounding.md index 26f4fe4..9a4f936 100644 --- a/docs/skill-grounding.md +++ b/docs/skill-grounding.md @@ -31,7 +31,7 @@ It's written for **agents operating the network** — often on behalf of a human ## B. About & references (an "About / further reading" section) -> Provenance and pointers — references and further reading, not authority. The skill's facts are bound to upstream *code* via the source-binding manifest, not to these pages. +> Provenance and pointers — references and further reading, not authority. Source-backed facts are bound to upstream *code* via the source-binding manifest; visibly provisional team-confirmed exceptions are recorded there pending upstream authority. These pages are not a binding source. **About this skill.** Built and maintained by the Autonomi team. It synthesises operator-relevant truth from the upstream Autonomi code into one agent-facing skill. Source: this repository. diff --git a/planning/HANDOFF.md b/planning/HANDOFF.md index c28d5de..b81d83c 100644 --- a/planning/HANDOFF.md +++ b/planning/HANDOFF.md @@ -1,59 +1,65 @@ -# Handoff — review entry & continuity +# Current state & handoff -> **For:** Hermes (review) and David (gate-holder). **From:** Jim. **Date:** 2026-06-25. -> **Heads-up:** Jim is **away and unavailable for a period** — can't unblock anything in real time. This doc is written so the team can keep moving without him. +> **Entry point** for anyone — human or agent — picking up the `autonomi` skill. **Owner:** Jim. **Updated:** 2026-09-05. Read this first for where things stand and what's next. ## TL;DR -The `autonomi` skill — teaching an agent to run Autonomi nodes and earn ANT, non-custodially — is rebuilt, source-bound, agent-tested, and ready to review. **Everything is now on `main`** — one branch, no open PRs to chase — so `npx skills add WithAutonomi/skills` installs it directly. This handoff maps the repo, states what you can decide while Jim's away, and how to test. +The `autonomi` skill — teaching an agent to run Autonomi nodes and earn ANT, non-custodially — is rebuilt, source-bound, and agent-tested to the preflight gate. The merged baseline lives at **`WithAutonomi/skills`** (private), installable by repository members with `npx skills add WithAutonomi/skills`; PR #12's `docs/state-refresh` branch is the current decision-review candidate. The rebuild and org transfer are done; work is now continuing on the open threads below. -**Start here:** `README.md` → `skills/autonomi/SKILL.md` → its `references/` → this doc → `planning/REBUILD-BRIEF.md` (the full rationale) → `docs/adr/`. Then run the test in `planning/TESTING.md`. +**Start here:** `README.md` → this doc → `planning/STATE.md` → `planning/packets/2026-Sep-05-pr12-review-remediation.md` → `skills/autonomi/SKILL.md` + its `references/` → `docs/adr/`. Historical rationale: `planning/REBUILD-BRIEF.md`. To test: `planning/TESTING.md`. -## What's in the repo (all on `main`) +## What's in the repository - **`skills/autonomi/`** — the installable skill: `SKILL.md` + `references/` (node provisioning, operating procedures, uninstall, wallet-and-tokens, troubleshooting). -- **`docs/adr/`** — the architecture decisions, ADR-0001 to ADR-0012, all **Proposed**. -- **`planning/`** — `REBUILD-BRIEF.md` (the rationale/contract), `node-resource-spec-brief.md` (for the dev team), `TESTING.md`, `NEXT-PHASE.md` (parked threads), `release-endpoint-accessibility.md` (an upstream flag), and the OpenCode packet. -- **`source-bindings/`** — provenance: every command/figure bound to upstream code (drives the planned auto-update). +- **`docs/adr/`** — architecture decisions, ADR-0001 to ADR-0014, all **Proposed**. +- **`planning/`** — `STATE.md` (committed checkpoints; live status stays on PR #12), `packets/2026-Sep-05-pr12-review-remediation.md` (current approved repair), `REBUILD-BRIEF.md` (historical rationale/contract), `node-resource-spec-brief.md` (for the dev team), `TESTING.md`, `NEXT-PHASE.md` (parked threads), and `release-endpoint-accessibility.md` (an upstream flag). +- **`source-bindings/`** — provenance: commands and sourced figures bound to upstream code; explicitly labelled team-confirmed values remain pending upstream authority (drives planned release regeneration). - `README.md`, `CONTRIBUTING.md`. -The repo is a single clean `main` — the earlier rebuild / brief / ADR branches have all been merged and removed, so there's nothing else to track down. +`main` contains the earlier rebuild. Proposed ADR-0013/0014 and the accompanying authority/freshness corrections remain on PR #12 until human review and merge. -## Governance while Jim is away +## Repo & operational facts -Agreed model: **David + Hermes self-approve within bounds.** +- **Home & owner:** `WithAutonomi/skills`, transferred from `JimCollinson/skills` (GitHub redirects the old URLs). Hermes signed off on the name/home (ADR-0007 / 0012). +- **Visibility — private for now.** It will go **public at launch**: public is what enables unauthenticated `skills.sh` installs and true clean-context testing, and it's also what actually switches branch protection on (below). While private, installing via skills.sh needs the runner's own GitHub auth (an org member with access). +- **Branch protection — configured but not enforced.** A `main-branch-protect` ruleset exists (require a PR, block force-push + deletion, require the ADR CI check, 0 required approvals), but GitHub only enforces rulesets on **private** repos under **GitHub Team+**, and this org is on the free plan. So it's currently **honour-system** — branch + PR by convention (`CONTRIBUTING.md`). It **auto-activates when the repo goes public** (or the org upgrades). +- **Agent/integration access:** because the repo is private, an external integration (automation, or an agent's GitHub tooling) needs an explicit org grant to reach it — otherwise it can't read or write the repo. +- **Install:** `npx skills add WithAutonomi/skills` (from `main`; while private, needs the runner's GitHub auth). -- **Proceed freely (review + merge):** skill content and wording, `references/`, `docs/` prose, `README`, `planning/` notes, troubleshooting, tests, bug fixes, source-binding corrections. Use branch + PR; David approves Hermes's PRs and vice-versa. -- **Hold for Jim (or take to the wider team):** **architecture / protocol / security** decisions and marking ADRs **Accepted**; **distribution-channel** changes; any further **repo/skill renaming**; anything touching **keys / custody / spend** (out of scope for the skill anyway). These aren't blockers for improving the skill — they're the few things to leave parked. -- **Transferred to `WithAutonomi/skills`** (private), with Hermes's sign-off on the name/home (ADR-0007 / 0012). It'll go public when ready to distribute. -- The **release-endpoint** item (below) is an upstream `ant-client` change — raise with the wider MaidSafe team, not gated on Jim. +## Working model & gates -ADR discipline holds: inspect `docs/adr/` before changing architecture; draft new decisions as **Proposed**; never edit an Accepted ADR (supersede instead). +- **Branch + PR** for changes — don't commit straight to `main` (protection is convention-only for now, so this runs on trust). +- **Proceed freely:** skill content and wording, `references/`, `docs/` prose, `README`, `planning/`, troubleshooting, tests, bug fixes, source-binding corrections. +- **Gated (needs an ADR and/or Jim):** architecture / protocol / security decisions and **accepting ADRs**; distribution-channel changes; repo/skill renaming; the **public flip**; anything touching keys / custody / spend (out of scope for the skill anyway). +- **ADR discipline:** inspect `docs/adr/` before changing architecture; draft new decisions as **Proposed**; never edit an Accepted ADR (supersede instead). ## State of the skill (what's done) -- **Source-bound:** every command, flag, and figure is tied to upstream `ant-client` / `ant-node` code (see `source-bindings/`). Where a figure leads the docs (the ~20 GB/node disk minimum), it's flagged inline as team-confirmed, pending source. +- **Source-bound with explicit exceptions:** every Autonomi-specific command and flag is tied to upstream `ant-client` / `ant-node` code (see `source-bindings/`); ordinary shell/OS observation must be checked for each claimed platform rather than misrepresented as an Autonomi claim. A figure that leads upstream documentation, such as the ~20 GB/node disk minimum, is labelled team-confirmed and pending source rather than presented as source-bound. - **Safety doctrine:** non-custodial (nodes only ever get a public `--rewards-address`); spending/custody is out of scope and gated; daemon stays on loopback; no key handling anywhere. - **Deliberate capacity model:** the agent decides what to contribute and where (which volume, how many nodes) up front, can place node data on other volumes via `--data-dir-path` (with the human's consent for their media), and monitors capacity over time. -- **Complete teardown:** `references/node-uninstall.md` covers nodes, daemon, CLI, custom/external data dirs, config paths, and a verification step. No OS service is involved (verified in source). +- **Teardown coverage with a Windows gap:** `references/node-uninstall.md` covers nodes, daemon, CLI, custom/external data dirs, config paths, and a verification step. No OS service is involved (verified in source), but Windows `PATH` cleanup remains incorrect and unverified as noted below. - **Reviewed:** a fresh adversarial pass flagged three things as "invented" that are in fact source-bound + live-tested (`DELETE /api/v1/nodes/{id}`, daemon ordering, network defaults) — docs lag the code. Lesson logged: review against the source manifest, not just the docs. - **Agent-tested:** an OpenCode agent installed the skill and ran it to the preflight gate, correctly and safely (details in `planning/TESTING.md`). +- **Proposed policy is ahead of the installed skill:** PR #12 changes decisions and documentation only. The current skill's "smaller, reversible action" wording has not yet been reconciled with ADR-0014's stricter no-mutation rule, and its broad “every command and figure” provenance wording has not yet been narrowed to the Autonomi-specific binding surface. The decisions remain Proposed rather than implemented guarantees. +- **Distribution is an internal preview:** skills.sh installation requires private-repository access. A legacy OpenClaw metadata block is present, but OpenClaw's current parser ignores its unsupported `shell` / `powershell` installer entries and `command` / `verifies` fields. There is no working OpenClaw installer or proven public ClawHub listing, and checksum/signature verification through that route has not been implemented. +- **Windows is unverified and currently inconsistent:** most unchanged operational recipes are Bash-oriented, including disk checks across `SKILL.md` and the node guides plus the read-only balance procedure in `wallet-and-tokens.md`. Provisioning and troubleshooting use Unix-only `export`; `node-provisioning.md`, `troubleshooting.md`, and `node-uninstall.md` all say the installer does not edit `PATH`, contradicting the source-bound Windows installer behaviour. These are known examples, not an exhaustive Windows audit. PR #12 documents the limitation rather than changing skill implementation; do not claim Windows support until a later implementation slice audits, corrects, and tests the complete path. -## Open items & Jim's guidance (so you're not blocked) +## Open threads (what's next) -1. **Org transfer + repo name — done.** Transferred to **`WithAutonomi/skills`** (private); Hermes confirmed the name/home (reasoning in ADR-0007 / 0012). Renamable later if needed. -2. **The decision ADRs (0007 / 0008 / 0012)** — on `main`, **Proposed**. Review and comment freely, but leave them Proposed; Jim marks them Accepted on his return. -3. **Release-endpoint accessibility** (`planning/release-endpoint-accessibility.md`). The `ant` binary serves from a CDN many agent sandboxes block. Directions + a PR-candidate are written up; raise with the wider team (likely Chris / the release process) — it's an `ant-client` change, not a skills-repo one. -4. **Node-resource SOP brief → dev team** (`planning/node-resource-spec-brief.md`). What an operating agent needs to understand (resource numbers + the standing/shunning/reward model) and the *form* the answers must take (hard values where knowable, explicit principles where judgement). The dev team should author a single authoritative *Recommended Node Resource Document* the skill source-binds to. Being shared with the team. -5. **Parked next-phase threads** (`planning/NEXT-PHASE.md`): UX/model tuning; the resource specs above; source-bound auto-update automation; consolidating the developer skill into this repo; and the **skill self-update mechanism** (§5 — how an installed copy learns it's stale across channels, not just skills.sh). -6. **Voice/behaviour ADRs not yet written.** The brief (§10) plans three: "no autonomy tiers," "skill voice — no internal vocabulary," and a tightening of ADR-0010 (modes design-only; two-register voice). Captured as intent; the team can author them. -7. **Keywords / discovery.** A supply-side keyword pass (`earn`, `spare-capacity`, etc.) and the `post-quantum` keyword call are open (brief §8). -8. **Full live end-to-end run.** Not yet done — needs a host with ≥ ~20 GB free, full egress (binary CDN + Arbitrum RPC), ideally no pre-existing nodes. See `TESTING.md`. +1. **Review the decision ADRs** — ADR-0007/0008/0010/0012/0013/0014 remain Proposed and need renewed human review before any acceptance decision. +2. **Full live end-to-end run** — the big unproven bit: we only reached the preflight gate. Proving a node comes up + a balance reads needs a host with ≥ ~20 GB free, full egress (binary CDN + Arbitrum RPC), ideally no pre-existing nodes. See `TESTING.md`. +3. **Node-resource SOP → dev team** (`planning/node-resource-spec-brief.md`) — the dev team to author a single authoritative *Recommended Node Resource Document* (resource numbers + the standing/shunning/reward model; hard values where knowable, explicit principles where judgement) that the skill source-binds to. Not yet picked up. +4. **Release-endpoint accessibility** (`planning/release-endpoint-accessibility.md`) — `ant`'s binary serves from a CDN many agent sandboxes block; an upstream `ant-client` change (likely Chris / the release process). +5. **Skill freshness & channel-owned updates — decided in ADR-0013 (Proposed).** Four mechanisms: documented tool-update context; reviewed source-bound regeneration; installation-channel delivery with no in-skill version probe; and a bounded, data-only, best-effort live check for volatile values. Release automation is staged in `NEXT-PHASE.md` §3; mechanism 4 depends on the resource document and a later protocol/spec. +6. **Parked next-phase** (`NEXT-PHASE.md`): UX / model-interpretation tuning; consolidating the developer skill into this repo. +7. **Voice/behaviour decisions — authored.** ADR-0010 amended (register runs two directions; translate by judgement, not find-and-replace); new **ADR-0014 (Proposed)** — autonomy is an input (no surfaced tiers), default-deny under uncertain remit, and a clean product surface (no internal vocabulary). Both Proposed, pending review. +8. **Keywords / discovery** (brief §8): a supply-side keyword pass + the `post-quantum` keyword call. ## How to test -See **`planning/TESTING.md`** — it has the repeatable agent-run prompt, the evidence so far, and what a full pass needs. +See **`planning/TESTING.md`** — the repeatable agent-run prompt, the evidence so far, and what a full pass needs. -## Contact +## Contacts -Jim is away and unavailable for a period. **David is the point of contact** in his absence. Feedback that would otherwise go to Jim: leave it in PR comments / `planning/` notes for his return. +Jim (owner); David and Hermes contribute. Raise decisions/questions via PR comments or `planning/` notes. diff --git a/planning/NEXT-PHASE.md b/planning/NEXT-PHASE.md index f32ca0b..2336d2d 100644 --- a/planning/NEXT-PHASE.md +++ b/planning/NEXT-PHASE.md @@ -15,14 +15,14 @@ The skill currently carries the **~20 GB/node** minimum as *team-confirmed, pend These belong in the **upstream repos** as the authoritative SOP, with the skill **source-binding** to them (same pattern as commands and flags). Full set of questions for that document: **`planning/node-resource-spec-brief.md`**. Until then, the figures stay flagged as team-confirmed. Tied to the body of work following the **2026-06-24 team call**. -## 3. Skill auto-update automation (from source-bindings) +## 3. Skill release automation (from source-bindings) -Not started — deliberately deferred until the skill is usable and in the right shape. The foundation is already here: `source-bindings/` binds every command and figure to upstream code at a pinned commit. The automation (per the rebuild brief's freshness model) watches upstream vs. the manifest → regenerates `SKILL.md`/`references/` → re-releases a version-pinned snapshot. Jim has prior art from the Docs repo to draw on. Owner: TBD, after the skill settles. **See also #5 (the consumer-side update mechanism), which this produces versions *for*.** +Not started — deliberately deferred until the skill is usable and in the right shape. The foundation is already here: `source-bindings/` binds commands and sourced figures to upstream code at pinned commits; team-confirmed exceptions remain explicitly labelled pending upstream authority. The automation (per the rebuild brief's freshness model) watches upstream vs. the manifest → regenerates `SKILL.md`/`references/` → re-releases a versioned snapshot. Jim has prior art from the Docs repo to draw on. Owner: TBD, after the skill settles. **See also #5 (consumer-side delivery), which this produces versions *for*.** ## 4. Consolidate the developer skill into this repo Move **`autonomi-developer`** (build *on* Autonomi) into `skills/` here, so the repo is the org's single first-party skills home. **Wait until the base `autonomi` skill is up on its feet.** It's non-trivial: the developer skill is draft/beta, carries its own automation, and pulls from the developer docs — a scheduled mini-project, not a copy. (The README lists it as Planned; the rebuild brief §2 has the reasoning.) -## 5. Skill self-update mechanism (consumer side) — decide the model +## 5. Skill updates (consumer side) — channel-owned -Distinct from #3 (which *produces* new skill versions). Question to settle: how does an installed copy of the skill **learn it's out of date and update**? Today the skill carries a frontmatter `version` and is installable via skills.sh, so `npx skills update` works — but there's no runtime "check on invocation" authored in the skill (x0x's `SKILL.md` doesn't author one either; its always-latest behaviour is binary-side + the skills.sh version field). Decide: rely on skills.sh's update flow, and/or add an explicit self-check instruction. Note the skill already has a *resilience* mechanism — it tells the agent to verify commands against the installed `ant --help` and trust the tool over the docs — so a stale skill self-corrects on facts even before a version update lands. +**Decided in Proposed ADR-0013 after a 5 September 2026 review of current first-party skills.** Installed-skill updates belong to the channel that installed the copy, or to deliberate reinstall for a manual copy. The skill makes no first-use network request to check its own version and never modifies its own files. The bundle keeps its resilience mechanism — learn the tool from `ant --help` and trust the tool over the skill — while task-specific, source-bound facts remain separate from self-version checking. ADR-0013's bounded live advisory for typed volatile values (mechanism 4) is still a later protocol/spec. diff --git a/planning/REBUILD-BRIEF.md b/planning/REBUILD-BRIEF.md index 2526264..9251a30 100644 --- a/planning/REBUILD-BRIEF.md +++ b/planning/REBUILD-BRIEF.md @@ -1,6 +1,6 @@ # Autonomi Skill — Rebuild Brief -> The single contract for rebuilding the skill, distilled from the read-through. Supersedes the scratch critique log. **Draft for Jim's review before committing to the repo `planning/`.** +> **Historical June rebuild contract.** The build has since landed; read `planning/HANDOFF.md` for current state and the Proposed ADRs for current decisions. The branch/status lines below are retained as design history, not present-tense instructions. ## 0. Approach @@ -35,7 +35,7 @@ Autonomi runs **quietly in the background**; the **agent absorbs the complexity* - **Three layers (the install ergonomics):** 1. **The skill bundle** = `skills/autonomi/` (`SKILL.md` + bundled `references/`) — the *only* thing that installs; agent-facing; self-contained. - 2. **`references/`** = a subset of that bundle — agent-facing depth, loaded on demand; **bundled, not linked** (offline / fresh-host / version-locked). + 2. **`references/`** = a subset of that bundle — agent-facing depth, loaded on demand; **bundled, not linked** (available without live docs after installation; version-locked). 3. **Repo-side only, never ships** = `docs/`, `docs/adr/`, `planning/`, `source-bindings/` — human/maintainer/process-facing (`source-bindings` exists to drive autonomous regeneration, not for the running agent). - Install discovery scans root + `skills/`, so it pulls **only layer 1**. The `skills//` subdir does double duty: multi-skill layout **and** the wall that keeps internal scaffolding out of the installed product — the "no internal stuff in the product" principle at the file level. - **Install behaviour (verified by running the CLI):** it clones the repo and discovers skills (root + `skills/` one level deep → finds `skills/autonomi/`). **One skill → installs it; multiple → an interactive multi-select picker** ("Select skills to install (space to toggle)") listing each skill's **name + description** — so the `description` is also the picker copy (another reason it must be strong). Flags: `--skill autonomi` (explicit/deterministic — use in install docs), `--all` (all), `-y` (non-interactive), `--list` (preview). `metadata.internal: true` hides a skill from discovery during build. @@ -55,7 +55,7 @@ Autonomi runs **quietly in the background**; the **agent absorbs the complexity* ## 5. SKILL.md structure (the spine — rich, front-loaded) -Order: frontmatter → **what Autonomi is** (network-first; ANT = Autonomi Network Token) → **key terms** (define `ant` vs ANT, node, daemon, public address) → **how you operate + safety invariants** (do-the-work / escalate-by-exception; non-custodial; never handle keys; spend/authority gated + surfaced; verify installs honestly; daemon on loopback unless authorised) → **get started** (detect/install → start → verify) → **what you can do** (intent menu → references) → **CLI reference** (core, source-bound) → compact **config (TOML) / storage / common-errors** blocks → **about**. +Order: frontmatter → **what Autonomi is** (network-first; ANT = Autonomi Network Token) → **key terms** (define `ant` vs ANT, node, daemon, public address) → **how you operate + safety invariants** (do-the-work / escalate-by-exception; non-custodial; never handle keys; authority grants/widening explicit, within-envelope action autonomous, reporting adaptive; verify installs honestly; daemon on loopback unless authorised) → **get started** (detect/install → start → verify) → **what you can do** (intent menu → references) → **CLI reference** (core, source-bound) → compact **config (TOML) / storage / common-errors** blocks → **about**. - **Scope line** near the top: covers running/managing nodes & earning ANT now; storing/retrieving your own data as the skill grows. - Front-load install/start/verify; not precious about length; **safety invariants live here** (never behind an on-demand reference). @@ -76,13 +76,13 @@ Order: frontmatter → **what Autonomi is** (network-first; ANT = Autonomi Netwo ## 7. Source-bindings, freshness & CI - **Repo-side only**, renamed off `tier1-*` → `source-bindings`. Binds **only what the skill uses/claims**: `ant-client`, `ant-node`, `evmlib` (`self_encryption` orientation-only until data-storage). Reconcile the shipped "synthesised repos" list to this subset. -- **Freshness model:** automation watches upstream vs the manifest → regenerates SKILL.md/references → **re-releases** a version-pinned snapshot. The using agent consumes the bundled snapshot (no runtime live-fetch). +- **Freshness model (see ADR-0013 for the authoritative model):** automation watches upstream vs the manifest → regenerates SKILL.md/references → **re-releases** a versioned snapshot; the using agent can load the bundled guidance without contacting a freshness service, while network operations still require their normal connectivity. New versions are delivered by the installation channel, or by deliberate reinstall for a manual copy, rather than by a self-version request inside the skill. ADR-0013 separately defines a **bounded, data-only, best-effort** runtime check for a narrow class of volatile values (resource/threshold figures), never free-form prose and never a hard dependency for access to the guidance. - **CI live-test owns command correctness** (not manual review) and is the seed for **troubleshooting** sourcing: upstream known issues + pitfalls anticipated from the code + **gated** agent field-reports (candidate → reproduce/validate → bind → ship). - **Install-endpoint accessibility (research + CI follow-up — Jim; not blocking the build):** `raw.githubusercontent.com` install URLs are sometimes blocked in agent sandboxes/allowlists while other GitHub URL types aren't. Research + test alternates — notably the **release `latest/download` URL on `github.com`** (`github.com/WithAutonomi/ant-client/releases/latest/download/…`, the x0x pattern), plus `api.github.com` and the jsDelivr CDN. Then (1) source-bind the per-platform release-asset URLs and add them as **install fallbacks** (provisioning + `kind: download` openclaw manifest entries, mirroring x0x); (2) add a **CI check that the install endpoints are reachable from a variety of agent environments/allowlists**, to catch a blocked URL before an agent does. - **Confirmed (2026-06-24):** `ant-client` DOES publish signed per-platform release archives on `github.com` — latest `ant-cli-v0.2.8`; assets `ant--.{tar.gz,zip}` (linux-musl x64/arm64, apple-darwin x64/arm64, windows-msvc) + `.sig` (ML-DSA-65) + `SHA256SUMS.txt`, at `github.com/WithAutonomi/ant-client/releases/download//`. Wrinkle: asset names are **version-stamped** and the tag is `ant-cli-vX.Y.Z`, so x0x's static `latest/download/` doesn't work as-is — resolve the latest version via `api.github.com/repos/WithAutonomi/ant-client/releases/latest`, then fetch the asset (both allowlist-friendly domains; neither raw.githubusercontent). Bonus: `install.sh` itself is fetched from raw.githubusercontent — the blocked hop — so a direct-asset fallback that skips the script is the real win, and it's verifiable via the `.sig`/SHA256SUMS. - **Live sandbox test (2026-06-24) — the blocker is the binary CDN, not the domain:** in a restricted agent sandbox, **reachable**: `raw.githubusercontent.com`, `api.github.com`, `index.crates.io`, `autonomi.com`; **blocked**: `release-assets.githubusercontent.com` (where release binaries actually serve — so `github.com/releases/download` AND the api-asset path both 302→403), `cdn.jsdelivr.net`, `static.crates.io` (no source build), `arb1.arbitrum.io` (balance RPC). Net: **`ant` could not be installed by any path, and balance couldn't be read** — so the github-releases fallback doesn't rescue this case. Implications: (1) the skill should **fail gracefully and name the domains to allowlist** (`release-assets.githubusercontent.com` for install; `arb1.arbitrum.io`/an explorer for balance) instead of flailing; (2) the read-only balance path needs **configurable RPC endpoints + fallbacks**; (3) a full live operational test needs a fuller-network host (the commands themselves are already source-validated by the manifest's live self-test). - **Live end-to-end verification = agent-run, full-egress (capture for CI).** The clean-context test must be an *agent* following the installed skill end-to-end (install → add → start → status → balance) and seeing the node come up healthy — **not** a human typing commands (the skill is agent-run; the human is never handed CLI). It needs an environment with the binary CDN (`release-assets.githubusercontent.com`) and the Arbitrum RPC (`arb1.arbitrum.io`) reachable — i.e. deliberately broader egress than a default agent sandbox, which blocks both (per the sandbox test above). So the CI/test runner is itself a setup requirement, not a given. -- **Per-node storage minimum = ~20 GB (team-confirmed 2026-06-24; not yet in source/docs).** To avoid **the individual node** being **shunned** (per-node — the network drops just that node, not the agent or machine), provision ≥ ~20 GB free disk per node — distinct from the hard 500 MiB write-reserve. Added to the skill (SKILL.md config, provisioning preflight, operating resource-strategy) **attributed inline as team-confirmed, pending source** — not faked as source-bound. **Follow-up:** record it in the `source-bindings` manifest as team-provenance, and **re-bind to code/docs when upstream catches up** (this is the model for team-confirmed figures that lead the docs). +- **Per-node storage minimum = ~20 GB (team-confirmed 2026-06-24; not yet in source/docs).** To avoid **the individual node** being **shunned** (per-node — the network drops just that node, not the agent or machine), provision ≥ ~20 GB free disk per node — distinct from the hard 500 MiB write-reserve. Added to the skill (SKILL.md config, provisioning preflight, operating resource-strategy) **attributed inline as team-confirmed, pending source** — not faked as source-bound. The accountable repository record, unresolved additive/shared semantics, and upstream revalidation path are now captured in `source-bindings/tier1-operate-and-earn.md`; **re-bind to code/docs when upstream catches up** (this is the model for team-confirmed figures that lead the docs). - **Gauntlet must review against source/manifest, not just docs (lesson, 2026-06-24 adversarial review).** A fresh reviewer with only the public docs flagged three *correct, source-bound, live-tested* things as "invented" — the `DELETE /api/v1/nodes/{id}` single-node removal, the daemon ordering (`add` needs no daemon; `start`/`stop` do), and the `--network-id`-not-forwarded / node-defaults-`arbitrum-one` behaviour — because `docs.autonomi.com` lags the code. Implication: **doc-only reviewers and CI will mis-flag code-bound-but-undocumented facts**, so the gauntlet (and any CI doc-check) must verify against the source-bindings manifest / upstream code, not the docs. Vindicates the skill's "trust the installed tool; docs lag" stance. The review also surfaced genuine small fixes (report-raw-balance/decimals, `SECRET_KEY` wording, daemon parenthetical, count-cap softening, `--upgrade-channel`, PATH note) — applied. ## 8. Keywords & scope diff --git a/planning/ROADMAP.md b/planning/ROADMAP.md index 30b285e..838d447 100644 --- a/planning/ROADMAP.md +++ b/planning/ROADMAP.md @@ -1,6 +1,6 @@ # Autonomi Operator Skill — Roadmap -> Canonical roadmap (the vault holds only a pointer). It sequences the work; it does not restate VISION, amend the ADRs, or write DESIGN. Two axes run through it: **build phases** (*how* we build — design → author → automate) and the **delivery scope ladder** (*what the skill does*, per capability tier). Phase 02 authors the ladder tiers in order. ADRs are referenced, not redefined; ADR **acceptance** is a human gate held by the decision owner (Jim) after the named reviewer's review (David Irvine), and any PR / merge / publish is a maintainer-approval gate. +> **Historical June sequencing baseline.** This preserves the original build phases and capability ladder; its checkbox statuses are not the current project state. Read `planning/HANDOFF.md` for current state and `planning/NEXT-PHASE.md` for active parked work. ADRs own decisions; ADR **acceptance** remains a human gate held by Jim after David Irvine's review, and any PR / merge / publish remains a maintainer-approval gate. ## Overview @@ -22,7 +22,7 @@ - [x] Operator scope, boundary, and interface stance set: existing `ant` CLI + node-management daemon, no new tooling, build frontier routes to the Developer skill — ADR-0003. - [x] Non-custodial node operation committed; wallet-address sourcing as a neutral menu (supplied / provisioned / agent-created); agent-created first-class for autonomous use via an out-of-context custody substrate (never LLM-created), secrets-out-of-context necessary-but-not-sufficient, declared recovery path at creation — ADR-0004. - [x] Spend-to-store understood and escalated: real path is ANT + native Arbitrum gas; **no upstream gasless path exists**; gas is a team strategy call, not an in-skill invention — ADR-0005. -- [x] Source-binding decided: every claim source-bound to upstream, volatile facts single-sourced, mechanically-derived vs judgement-derived split, plus the cross-repo freshness contract — ADR-0006. +- [x] Provenance decided: source-backed claims bind to upstream, temporary team-confirmed exceptions remain explicit and pending upstream authority, volatile facts stay single-sourced, and the mechanically-derived vs judgement-derived split plus cross-repo freshness contract are fixed in ADR-0006. - [x] Repo home and lifecycle decided: standalone repo, org-owned before public; independent lifecycle, no lockstep between skill / `ant` / `ant-node`; source bindings are provenance, not runtime pins — ADR-0007, ADR-0009. - [x] DESIGN substantially complete and realigned to ADR-0001…0009 (including the capability ladder, §12). - [x] Repo published and under review (`JimCollinson/autonomi-skill`, David a collaborator; Hermes/David review pass). @@ -30,8 +30,8 @@ - [ ] **Agent wallet custody substrate** decided — where keygen / storage / recovery / signing live (assumed-host / signposted / skill-provided wrapper / upstream `ant` / staged). Open team decision; gates Tier 2/3 — ADR-0004. - [ ] **Gas strategy** decided — the route that lets earned ANT actually be spent (agent ETH float / pre-funded envelope / faucet-grant / paymaster / defer). Open team decision; gates Tier 3 — ADR-0005. - [ ] Source-binding manifest format pinned (the `source_evidence` vs `tested_with` / `requires_min` / `known_incompatible` shape) before authoring — ADR-0006, ADR-0009. -- [ ] Close-group size resolved (read as both 5 and 7 in source) — pin or fetch-live before authoring runbooks. -- [ ] Pre-publish housekeeping confirmed: org transfer (→ WithAutonomi), licence (likely MIT OR Apache-2.0 — TBC), and the clean install / version-manifest URL — ADR-0007, ADR-0008. +- [ ] Close-group size resolved (read as both 5 and 7 in source) — pin it or define an approved, bounded fetch-live contract before authoring runbooks. +- [ ] Pre-publish housekeeping confirmed: org transfer (→ WithAutonomi), licence (likely MIT OR Apache-2.0 — TBC), and clean install/update routes — ADR-0007, ADR-0008. **Definition of Done:** - DESIGN substantially complete and the load-bearing ADRs drafted as Proposed — **essentially met**. The phase closes when the ADRs are accepted (Jim as decision owner, after David's review) and the two open team decisions (custody substrate, gas strategy) are recorded, the manifest format and close-group size are pinned, and the pre-publish items are resolved. ADR acceptance is a human gate; the custody and gas calls are team decisions, not @pm/agent calls. @@ -49,7 +49,7 @@ *Foundation (spans all tiers):* - [ ] Lean, routing-first SKILL.md authored (opener, task routing, core concepts, safety boundaries, routing table) per DESIGN §2; metadata/frontmatter, provenance/attribution, and install manifest on x0x's `metadata.openclaw.install` pattern — ADR-0008. - [ ] Skill-led, non-mutating install + verified delivery: detect/install the existing `ant` only when missing, confirm checksums + ML-DSA-65 signatures before use, clean uninstall path — ADR-0008, ADR-0009. -- [ ] Source-binding manifest populated as content lands (provenance per claim; volatile facts single-sourced; bake-with-pin vs fetch-live per fact) — ADR-0006. +- [ ] Source-binding manifest populated as content lands (provenance per claim; volatile facts single-sourced; bake-with-pin vs approved, bounded fetch-live per fact) — ADR-0006. *Tier 1 — Operate and earn (authored first; unblocked now):* - [ ] `node-operation.md`: install, run one/many, configure, monitor (`ant node status`, daemon `/api/v1/events` SSE), upgrade/stop, clean uninstall. @@ -76,15 +76,16 @@ ## Phase 03: Automate freshness -**Goal:** Turn the regeneration-ready structure into a working pipeline so the skill is kept current mechanically rather than by hand — the deferred half of ADR-0006. +**Goal:** Turn the regeneration-ready structure into a working pipeline so the skill is kept current mechanically rather than by hand — the deferred half of ADR-0006. ADR-0013 separates publisher-side regeneration, installation-channel delivery, and the deferred live-values mechanism. **Milestones:** -- [ ] Version self-check live: the skill fetches a manifest from an Autonomi-controlled URL and warns if stale, continues if offline — ADR-0006. +- [ ] Versioned releases flow through supported install channels: skills.sh's native global update comparison and project reinstall flows, versioned plugin updates for marketplaces, and a documented reinstall path for manual copies — ADR-0013. - [ ] Upstream-sweep pipeline: analyses the enumerated upstream watch-set, regenerates mechanically-derived content, flags judgement-derived content for review — ADR-0006. -- [ ] Cross-repo freshness contract operational: upstream repos signal operator-facing changes (issue/PR or release-note marker the freshness check consumes) — ADR-0006, ADR-0007. +- [ ] Cross-repo freshness contract operational: upstream repos signal operator-facing changes (issue/PR or release-note marker the regeneration pipeline consumes) — ADR-0006, ADR-0007. +- [ ] **Deferred mechanism-4 dependency:** publish the authoritative values document and approve a detailed protocol/spec before implementing the bounded runtime values check — ADR-0013 (mech 4). Until then, the reviewed bundled values remain the only source. **Definition of Done:** -- An installed copy self-reports staleness, and an upstream change to a source-bound fact is detected and routed to regeneration-or-review without a manual rewrite. (Structure is mandatory from Phase 02; the pipeline itself is explicitly deferred per ADR-0006 and may begin only after the watch-set and "material change" policy are settled.) +- A released update is discoverable through each supported installation channel, and an upstream change to a source-bound fact is detected and routed to regeneration-or-review without a manual rewrite. (Structure is mandatory from Phase 02; the pipeline itself is explicitly deferred per ADR-0006 and may begin only after the watch-set and "material change" policy are settled.) --- diff --git a/planning/STATE.md b/planning/STATE.md new file mode 100644 index 0000000..2953ea6 --- /dev/null +++ b/planning/STATE.md @@ -0,0 +1,28 @@ +# Execution state + +## Current Position + +- Phase: PR #12 review remediation +- Plan: resolve David Irvine's four findings and align ADR-0013 with Jim's channel-owned update decision +- Task: implementation and verification +- Status source: live checks and review activity on [PR #12](https://github.com/WithAutonomi/skills/pull/12); the committed details below are a checkpoint, not a prediction of current GitHub state +- Mode: attended; stop before merge or ADR acceptance + +## Verification Context + +- Meaningful work-unit: yes — Proposed ADR and operational-authority semantics +- Local fast gate: no `.gsd/gate.sh` exists +- CI arbiter: GitHub Actions `ADR Governance` check on PR #12 / branch `docs/state-refresh` +- Green of record: read the exact-head `ADR Governance` result on PR #12; no local result substitutes for CI +- Required reviews: code/ADR review, goal verification, adversarial, Craft Review, clean-context panel +- Review deferral: none + +## Current Session + +- Date: 2026-09-05 +- Agent: OpenCode +- Outcome: At exact head `638650646688bef05eb417f0600536706974f04c`, CI, goal verification, and ADR review passed. Adversarial review passed its blocking threshold but found two medium current-state gaps: the handoff still called teardown complete despite the disclosed Windows uninstall defect, and the Windows inventory omitted the Bash-only balance procedure. Craft Review raised the same inventory gap as a conformance concern. A supplementary fresh-context read found the branch discoverable without chat context, but noted that this file intentionally records the prior checkpoint while PR #12 is the live status source, and that the packet's whitespace check should cover the full PR range. This follow-up removes the teardown overclaim, describes the skill's Bash-oriented recipes without pretending to provide an exhaustive Windows audit, includes the balance procedure, corrects one oversimplified skills.sh roadmap phrase, and makes the packet's diff check branch-wide. The official Fable clean-context route remains blocked because its required formal dispatch and lock authorization are not available. +- Review backlog at this checkpoint: the first pushed head containing these final current-state corrections needs exact-head verifier, adversarial, Craft, clean-context, ADR, and CI results recorded in PR #12; any later head invalidates that evidence +- Forks: none +- Parked units: none +- Checkpoint handoff: validate and push the current-state corrections, update the live PR body with its exact SHA, and rerun every exact-head gate; if all required checks pass, request David's human re-review diff --git a/planning/TESTING.md b/planning/TESTING.md index 809160e..66cf663 100644 --- a/planning/TESTING.md +++ b/planning/TESTING.md @@ -69,6 +69,8 @@ REPORT BACK Autonomi from this skill alone? What was missing, unclear, or wrong? ``` +> **Testing an unmerged branch:** the prompt above installs from `main`. To test a change that isn't merged yet, install from its branch instead — but give that branch a **slash-free name**, because `skills.sh` can't parse an install tree-URL whose branch name contains a slash (what tripped Run 1 above). + ## What a full end-to-end pass needs - **Disk:** ≥ ~20 GB free on the chosen data volume. On a machine whose system drive is tight, the skill will look for another mounted volume (e.g. an external drive) and place node data there via `--data-dir-path` — so an external drive with space is a valid way to get a real run on an otherwise-full machine. diff --git a/planning/channel-update-research.md b/planning/channel-update-research.md new file mode 100644 index 0000000..bd096c2 --- /dev/null +++ b/planning/channel-update-research.md @@ -0,0 +1,37 @@ +# Channel-owned skill update research + +Date: 2026-Sep-05 + +## Question + +Should an ordinary installed skill check its own version when loaded, or should the installation channel own update discovery and delivery? + +## Evidence + +Eight current first-party skill collections were inspected at fixed revisions. The documentation-path column records an independent fixed-revision verification on 2026-Sep-05; the original review did not preserve its path list. + +| Collection | Revision | `SKILL.md` count | Collection documentation inspected | +| --- | --- | ---: | --- | +| [Stripe AI](https://github.com/stripe/ai/tree/68382523846ea5bfad75ba1ef58dc5db031d0a5a) | `68382523846ea5bfad75ba1ef58dc5db031d0a5a` | 48 | `README.md`; `providers/README.md` | +| [Anthropic skills](https://github.com/anthropics/skills/tree/41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f) | `41bbe19d1a1a7eaab5e7bb9050a417e5c6cffc8f` | 20 | `README.md` (installation only; no update guidance found) | +| [Vercel agent skills](https://github.com/vercel-labs/agent-skills/tree/063bee94c3f4df8453406c830b0a7df0f2860278) | `063bee94c3f4df8453406c830b0a7df0f2860278` | 9 | `README.md` (installation only; no update guidance found) | +| [Cloudflare skills](https://github.com/cloudflare/skills/tree/b8aeca6d7e2d614d7bd0e5220c8dd7645fe58a93) | `b8aeca6d7e2d614d7bd0e5220c8dd7645fe58a93` | 13 | `README.md` (installation only; no update guidance found) | +| [Sentry for AI](https://github.com/getsentry/sentry-for-ai/tree/6a9642c5b01d7b91daa253a8de4a3ef39c639562) | `6a9642c5b01d7b91daa253a8de4a3ef39c639562` | 34 | `README.md`; `packages/installer/README.md`; plugin README files under `src/plugins/` | +| [Supabase agent skills](https://github.com/supabase/agent-skills/tree/8331f910845103c08d51f6ca1d86ebb7d1f745e3) | `8331f910845103c08d51f6ca1d86ebb7d1f745e3` | 2 | `README.md` (installation only; no update guidance found) | +| [Hugging Face skills](https://github.com/huggingface/skills/tree/97862b0fcc89c850fdd00c82ede1e62d3c930a6d) | `97862b0fcc89c850fdd00c82ede1e62d3c930a6d` | 26 | `README.md` (`hf skills update`) | +| [Shopify AI Toolkit](https://github.com/Shopify/Shopify-AI-Toolkit/tree/2619755e4f4e908fb205e889bac769de1767d40f) | `2619755e4f4e908fb205e889bac769de1767d40f` | 22 | `README.md`; `.hermes-plugin/README.md` | +| **Total** | | **174** | | + +Method: enumerate each revision's recursive Git tree, retain blobs whose path ends in `SKILL.md`, search every blob for `version|update|upgrade|outdated|latest|refresh|sync|manifest|remote|fetch|curl|wget`, inspect each match in context, then inspect collection-level installation/update documentation. The read-only command pattern is: + +```sh +gh api "repos/${repo}/git/trees/${sha}?recursive=1" --jq '.tree[] | select(.type == "blob" and (.path | endswith("SKILL.md"))) | [.path, .sha] | @tsv' +``` + +Each returned blob was read at its SHA with `gh api -H 'Accept: application/vnd.github.raw+json' "repos/${repo}/git/blobs/${blob_sha}"` and searched with `rg -n -i 'version|update|upgrade|outdated|latest|refresh|sync|manifest|remote|fetch|curl|wget'`. All eight trees reported `truncated: false`. This fixed-revision candidate review found no ordinary `SKILL.md` checking its own version when loaded; it does not prove that no differently worded implementation could exist. The collections that documented update behaviour assigned it to an installation channel or product CLI; runtime fetching described inside skills was task-specific rather than self-version checking. + +The skills.sh implementation was separately checked at [`vercel-labs/skills@5527c09adc367612b0bffd9c80e3bc28a6b01b6d`](https://github.com/vercel-labs/skills/tree/5527c09adc367612b0bffd9c80e3bc28a6b01b6d). Global updates in [`updateGlobalSkills`](https://github.com/vercel-labs/skills/blob/5527c09adc367612b0bffd9c80e3bc28a6b01b6d/src/update.ts#L284-L485) use stored source/ref/path identity and compare folder hashes before reinstalling changed content (GitHub comparison lines 370-372; cloned-source comparison lines 405-407). Project updates select non-local lock entries in [`getProjectSkillsForUpdate`](https://github.com/vercel-labs/skills/blob/5527c09adc367612b0bffd9c80e3bc28a6b01b6d/src/update.ts#L224-L239), then [`updateProjectSkills`](https://github.com/vercel-labs/skills/blob/5527c09adc367612b0bffd9c80e3bc28a6b01b6d/src/update.ts#L487-L648) reinstalls selected, non-deleted skills without a folder-hash comparison. Its recorded `ref` may be a branch or tag and is resolved again during update, so a recorded ref is not by itself an immutable pin; a content-addressed commit SHA or channel-enforced immutable release identifier is needed for that guarantee. Neither update path uses skill frontmatter as a semantic-version comparison contract. + +## Decision Input + +Jim chose the channel-owned pattern for Autonomi: the installed skill performs no request solely to check its own version and never updates itself. Managed installation channels use their own update mechanism; manually copied bundles require deliberate reinstall. Proposed ADR-0013 records the durable decision. Channel-specific implementation commands and reload behaviour remain source-bound implementation documentation rather than ADR content. diff --git a/planning/node-resource-spec-brief.md b/planning/node-resource-spec-brief.md index b0272fa..4628cc0 100644 --- a/planning/node-resource-spec-brief.md +++ b/planning/node-resource-spec-brief.md @@ -26,7 +26,7 @@ So the gaps are visible — the skill encodes this today (source-bound or team-c - A node **does not self-throttle** CPU/RAM — capping is the operator's job (OS-level). - Storage share is **network-set** (grow by adding nodes); spread ≈ **2/IP, ≈5/subnet** (excess nodes unused); ~**7×** replication. - **~20 GB free disk per node** to avoid that node being shunned *(team-confirmed, pending source)*, assumed additive. -- No OS service is installed (daemon/nodes are supervised processes); installer doesn't edit PATH. +- No OS service is installed (daemon/nodes are supervised processes). The Unix installer does not edit `PATH`; the Windows installer updates the user's persistent `PATH` and the current process. The current skill guidance does not yet preserve that platform distinction and remains unverified on Windows. Notice what's missing: **how earning works, what "healthy" means to the network, what the agent can actually see, and the authority it's operating under.** Those are the real gaps. @@ -118,5 +118,4 @@ These are the **hard values** the document must state — not describe. For each ## How the skill will consume this -One authoritative, **versioned** document at a stable upstream path, in **two registers**: the **values block** delivered structured and machine-readable so the skill **source-binds** each figure (like commands and flags) and the agent reads it rather than inferring it; and the **principles/guidance** carried as operating doctrine (the skill already does this — the boundary model, don't-churn, yield-to-the-host). The freshness automation re-pins when values change, and the skill can do a best-effort runtime **advisory check** for the volatile parameters (see `planning/NEXT-PHASE.md` §5) → until the document exists, the affected figures stay flagged *team-confirmed, pending source*. The items that would most change how well an agent operates are the **reward model (A)**, the **standing-observability gap (D)**, and the **shunning model (D)** — but every figure in the parameters list needs to arrive as a hard value, and every judgement call as an explicit principle. - +One authoritative, **versioned** document at a stable upstream path, in **two registers**: the **values block** delivered structured and machine-readable so the skill **source-binds** each figure (like commands and flags) and the agent reads it rather than inferring it; and the **principles/guidance** carried as operating doctrine (the skill already does this — the boundary model, don't-churn, yield-to-the-host). The freshness automation re-pins when values change, and the skill can do a best-effort runtime **advisory check** for the volatile parameters (see Proposed ADR-0013 mechanism 4) → until the document exists, the affected figures stay flagged *team-confirmed, pending source*. The items that would most change how well an agent operates are the **reward model (A)**, the **standing-observability gap (D)**, and the **shunning model (D)** — but every figure in the parameters list needs to arrive as a hard value, and every judgement call as an explicit principle. diff --git a/planning/packets/2026-Sep-05-pr12-review-remediation.md b/planning/packets/2026-Sep-05-pr12-review-remediation.md new file mode 100644 index 0000000..757199c --- /dev/null +++ b/planning/packets/2026-Sep-05-pr12-review-remediation.md @@ -0,0 +1,91 @@ +# GSD Work Packet — PR #12 review remediation + +Date: 2026-Sep-05 +Prepared by: OpenCode +Requested agent/tool: OpenCode and independent reviewers +Role requested: Implementer, verifier, adversarial reviewer, Craft reviewer, clean-context reviewer +Review mode: Full ADR/documentation review + +## Project / workspace + +Project: Autonomi skill +Repo/path: `/Users/jimcollinson/code/skills` +Current source of truth: PR #12 branch `docs/state-refresh` plus David Irvine's reviews at head `7f3b2e2690975184ab88aba3910cbbe05b597812` + +## Goal + +Make PR #12 ready for renewed human review by resolving David's four outstanding findings and aligning Proposed ADR-0013 with Jim's later channel-owned update decision. + +The four findings are: + +1. Installed-skill updates belong to the installation channel; do not add an in-skill self-version request. +2. Safety and authority gates are identical across contexts; only disclosure and escalation routing vary. +3. Missing, ambiguous, or exceeded remit permits only necessary non-mutating observation, followed by asking, escalating, or deferring. +4. Acting inside an affirmative existing envelope needs no per-action approval; granting or widening authority remains explicit. + +## Read first + +- `CONTRIBUTING.md` +- `docs/adr/TOOLING.md` +- David Irvine's reviews on PR #12 +- Proposed ADR-0004, ADR-0008, ADR-0009, ADR-0010, ADR-0013 and ADR-0014 +- `docs/DESIGN.md` §4 and §13 + +## Stage + +Implementation + +## Approved slice + +Repair PR #12's decision and planning documents, validate them, push the revised head, and update the PR for human re-review. Stop before merge or ADR acceptance. + +## Scope + +- Preserve and finish the inherited uncommitted authority/remit corrections. +- Make channel-owned installed-skill updates the Proposed ADR-0013 decision; remove the proposed in-skill self-version check. +- Reconcile active design and planning references with those decisions. +- Update PR #12's title/body and evidence after verification. + +## Out of scope + +- Skill implementation or runtime behaviour. +- Accepting any ADR. +- Merging PR #12 or PR #13. +- Rebasing or otherwise changing PR #13. +- Repository visibility or publication. + +## Constraints / forbidden actions + +- Preserve all inherited uncommitted work unless a line conflicts with Jim's later channel-owned update decision. +- Do not edit Accepted ADRs; all changed ADRs must remain Proposed. +- Do not weaken remit, custody, spend, or human-governance gates. +- No test, CI, harness, build, or environment changes. + +## Unattended mode / rigor profile + +Unattended mode: No + +Rigor profile: Full review because this changes Proposed architectural and authority decisions. Run local validation, independent adversarial review, Craft Review, verification, and a clean-context documentation review before requesting human approval. + +## Verification required + +- `GITHUB_BASE_REF=main python3 scripts/adr-governance.py` +- `git diff --check origin/main...HEAD` +- Focused search for superseded self-check and authority wording in active changed documents +- Confirm all changed ADRs remain Proposed and no Accepted ADR changed +- GitHub ADR Governance CI on the pushed exact head +- Independent adversarial, Craft, verifier, and clean-context results + +No `.gsd/gate.sh` exists. GitHub Actions `ADR Governance` on PR #12 is the only CI arbiter and covers ADR structure/governance, not semantic correctness. + +## Stop conditions + +Stop and report if the repair requires changing an Accepted ADR, implementation, CI/test machinery, or a decision not already made by Jim. Stop before merge, publication, repository visibility changes, or ADR acceptance. + +## Required output + +- Files and decisions changed +- Local and CI evidence +- Review findings and dispositions +- Remaining human gate +- Exact pushed head diff --git a/source-bindings/tier1-operate-and-earn.md b/source-bindings/tier1-operate-and-earn.md index 44bb199..1c9e9d3 100644 --- a/source-bindings/tier1-operate-and-earn.md +++ b/source-bindings/tier1-operate-and-earn.md @@ -1,6 +1,6 @@ # Source-binding manifest — Tier 1 operate-and-earn -Purpose: bind every Tier 1 command, flag, volatile constant, and important factual claim to upstream source. `source_evidence` proves a claim; `tested_with`, `requires_min`, and `known_incompatible` are compatibility axes and are deliberately separate. +Purpose: record provenance for every Tier 1 Autonomi-specific command, flag, volatile constant, install behaviour, and important factual claim. `source_evidence` binds a claim to upstream; a temporary `team-confirmed` exception records accountable provenance and remains pending upstream source. Ordinary operating-system/shell observation commands are outside the Autonomi binding surface but require platform-aware review. `tested_with`, `requires_min`, and `known_incompatible` are compatibility axes and are deliberately separate. ## Upstream revisions read @@ -104,6 +104,13 @@ source_evidence: - ant-client `ant-cli/src/main.rs` and ant-node `src/bin/ant-node/main.rs` both force at least 4 Tokio worker threads. ant-client lines 21-28 at commit `4d0448458ec302af68a5504c533d105b0991c93c`; ant-node lines 91-99 at commit `c53665bf4dda87cdbcf848606fa0182e822297d7`. - ant-client `ant-cli/src/commands/node/daemon.rs::BindArgs` says default daemon bind is `127.0.0.1` and binding to non-loopback exposes node management because the daemon has no authentication. Lines 9-25 at commit `4d0448458ec302af68a5504c533d105b0991c93c`. +Team-confirmed exception pending upstream source: + +- **Claim:** provision approximately 20 GB free disk per node as a strong recommendation to reduce the risk of that individual node being shunned. This is not a network-enforced limit and is distinct from the source-backed 500 MiB write reserve. +- **Accountable confirmation record:** Jim Collinson recorded the result of the 2026-06-24 team call in repository commit `25f7ebc07756418c210e6e83a0e3cfc8d14d4a1b`, `planning/REBUILD-BRIEF.md` section 7. Jim owns this repository record; the original team speaker was not named in the repository. That record, rather than an upstream code or documentation claim, is the present authority. +- **Known uncertainty:** upstream has not yet published the value or its semantics. In particular, whether approximately 20 GB is additive per node or a shared pool remains unresolved; the current skill assumes additive sizing and labels the value team-recommended/pending source. +- **Revalidation path:** the Autonomi team authors the versioned Recommended Node Resource Document specified by `planning/node-resource-spec-brief.md`; this entry is then replaced with an upstream repo / file / symbol-or-section / commit binding. Until then, regeneration and review must preserve the exception label and uncertainty. + ## Command and flag bindings ### `ant` top-level