From b7468a38ed4e5fc7042c31160e0e177af6a42c69 Mon Sep 17 00:00:00 2001 From: Joe Blau Date: Fri, 16 Oct 2026 16:08:22 -0700 Subject: [PATCH] docs: complete skill delivery and track live validation (#37) --- docs/ACCEPTANCE.md | 2 +- docs/PROGRESS.md | 4 ++-- docs/issues/37.md | 14 ++++++++++---- docs/issues/39.md | 7 +++++++ docs/issues/ROADMAP.md | 2 +- docs/testnet.md | 4 +++- packages/agent-cli/scripts/e2e-testnet.mjs | 2 +- 7 files changed, 25 insertions(+), 10 deletions(-) diff --git a/docs/ACCEPTANCE.md b/docs/ACCEPTANCE.md index 1d81a1f..2e02190 100644 --- a/docs/ACCEPTANCE.md +++ b/docs/ACCEPTANCE.md @@ -18,7 +18,7 @@ Node 22.12 minimum. | #26–#28 | Private PID/socket lifecycle, stale dead-PID recovery/readiness, serialized RPC, cross-network/config refusal and direct fallback only on confirmed absence; simulated WS drop, SDK resubscribe, paginated info gap-fill, persisted fill dedupe. Windows ACL limitations are documented. | | #29–#32 | Locked sequence journal across independent writers/restarts, replay/types/follow, exact fill fee units; log filtering/redaction; runner heartbeat/staleness and deposit polling; mocked-clock expiry blocking and once-per-threshold warnings. | | #33–#36 | New approval verified before signer handoff/old revocation, resumable rotation and immediate local revocation tests; fsynced cross-process hash-chain with intent/decision/signature digest/response/fill linkage; tamper/redaction tests and linked full-lifecycle records. CLI/RPC pre-schema hex/mnemonic detector and threat model. | -| #37–#38 | Skill source/frontmatter/error-catalog tests and every documented command input parsed through actual CLI schemas offline; user-owned Privy, ordered external approvals, bounded polling, exchange reconciliation and supported-test-route guidance; install/custody README, generated command reference and static Pages site. A real coding-agent testnet session is still unproven. | +| #37–#38 | Skill source/frontmatter/error-catalog tests and every documented command input parsed through actual CLI schemas offline; user-owned Privy, ordered external approvals, bounded polling, exchange reconciliation and supported-test-route guidance; install/custody README, generated command reference and static Pages site. The skill deliverable is complete; the unproven coding-agent testnet session is tracked explicitly in #39. | | #39 | Offline full CLI/SDK/RPC account lifecycle test and testnet-driver assertions; separate nightly script signs only for an acknowledged disposable CI test account, uses mocked Relay and already funded test collateral, reconciles exchange outcomes and exports event/audit/report artifacts. Explicit live execution fails when prerequisites are missing. Nightly live evidence remains pending. | | #40–#42 | Script-free packed global installation and installed bunx smoke, executable bin, license and matching skill versions; Node 22.12/24 install CI; Linux/macOS ARM/x64 native binary smoke; changesets/tagged-main/version/provenance/asset pipeline with candidate-only manual runs. Publishing and public registry verification await npm configuration. | | #49 | Token guard rejects declarations anywhere in formatted/minified CSS. Unit regression and a mutation of global.css prove docs:check rejects the issue's exact same-line copy. | diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index e7142d7..92e7ca9 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -39,9 +39,9 @@ | #34 | done | Optional cancel-all, resumable master revocation payload, immediate local blocking and config/session clearing after exchange submission. | | #35 | done | Cross-process locked fsynced hash-chain audit, intent/decision/signature digest/response/fill linkage, rotation/revoke records and filters; tamper/redaction tests. | | #36 | done | Pre-schema recursive CLI/RPC secret detector, BIP39-like seed rejection, private authorization refs and env/log/error scrubbing; threat model docs. | -| #37 | partial | User-owned Privy guidance, resumable approval/funding stages, exchange reconciliation and complete schema-validated command examples/error table. Canonical /SKILL.md is generated from the packaged source, linked from llms.txt/the skill guide and checked for byte parity. Offline tests pass; an actual coding-agent testnet session still needs dedicated QA credentials and evidence. | +| #37 | done | Skill content, packaged/embedded installation, schema-validated examples and public /SKILL.md hosting are complete. Frontmatter, gotchas, error handling, discovery links and source parity are verified. The unverified live coding-agent testnet criterion is explicitly transferred to #39. | | #38 | done | Install/testnet README, custody architecture, schema-generated command reference and static docs site with gated Pages workflow. | -| #39 | partial | Full mocked CLI/SDK/RPC lifecycle and fail-closed testnet harness, with builder approval, exchange outcome reconciliation, runner/events, rotation/revoke and audit assertions. Nightly live execution and journals need a disposable funded QA account and QA Privy app; missing credentials cannot count as a pass. | +| #39 | partial | Full mocked CLI/SDK/RPC lifecycle and fail-closed testnet harness, with builder approval, exchange outcome reconciliation, runner/events, rotation/revoke and audit assertions. Nightly live execution/journals and the independent coding-agent skill session transferred from #37 need dedicated QA setup and evidence; neither is claimed complete. | | #40 | partial | Script-free tarball global install and actual installed bunx help/schema smoke pass locally; executable/skill/license checks and Node 22.12/24 macOS/Linux CI. Public registry installation awaits publication. | | #41 | partial | Validated Changesets patch workflow with optional version PR, native binary smoke/checksums, tagged-main version gates, exact tested tarball publication with provenance and registry verification. Manual candidates cannot publish. Actual release needs npm authentication and the publishing gate; organization policy blocks automatic version PRs, so the default workflow uploads a reviewable patch. | | #42 | done | Final packaged flow audited and corrected (network/config isolation, exact loss/exposure/receipt checks, trigger preservation, readiness and stream errors). Skill shipped/embedded in npm and compiled CLI; Claude/Codex installation with CODEX_HOME, version synchronization, idempotency and overwrite protection. | diff --git a/docs/issues/37.md b/docs/issues/37.md index 7dfb796..a33a7ae 100644 --- a/docs/issues/37.md +++ b/docs/issues/37.md @@ -6,10 +6,16 @@ Labels: Skill & Docs, size:M Write `SKILL.md` with YAML frontmatter (`name: agent-cli`, `description`). Content: exact sequence init → fund (show QR) → poll `status` until deposit settled → `run`; how to call commands and parse JSON; reading `events --follow` and reacting (fills, errors, expiry warnings); error code handling table (retry vs stop); gotchas: 8-decimal perps USDC, two-signature deposit, agent expiry max 180 days, never ask for/paste master key, policy limits. ## Acceptance criteria -- [ ] Frontmatter valid -- [ ] Every command documented with example in/out -- [ ] Gotchas section complete -- [ ] Tested by running an agent through testnet flow +- [x] Frontmatter valid +- [x] Every command documented with example in/out +- [x] Gotchas section complete +- [x] Published at https://bloxwap.github.io/agent-cli/SKILL.md with source-parity checks + +## Live validation moved to #39 +The original criterion **Tested by running an agent through testnet flow** is +unverified and now tracked explicitly in #39. This issue covers the completed +skill content, installation and public hosting; moving the check does not claim +that a live agent session has passed. ## Dependencies - #12 diff --git a/docs/issues/39.md b/docs/issues/39.md index 34068f2..30d260b 100644 --- a/docs/issues/39.md +++ b/docs/issues/39.md @@ -9,6 +9,12 @@ Scripted e2e on HL testnet: init (with test master key in CI only), fund (mocked - [ ] Runs in CI nightly with secrets - [ ] Covers full lifecycle - [ ] Artifacts: events + audit logs +- [ ] Run a coding agent using the installed/hosted skill through the dedicated testnet flow; record agent/session ID, commit, lifecycle report and event/audit artifacts (moved from #37) + +## Agent skill validation (from #37) +The live coding-agent session remains unverified. It is separate from the +deterministic CI harness and offline fixture tests. #37 covers the completed +skill deliverable; this issue owns both forms of live testnet evidence. ## Dependencies - #27 @@ -16,6 +22,7 @@ Scripted e2e on HL testnet: init (with test master key in CI only), fund (mocked - #33 - #34 - #35 +- #37 ## Size L diff --git a/docs/issues/ROADMAP.md b/docs/issues/ROADMAP.md index a047643..5857e3c 100644 --- a/docs/issues/ROADMAP.md +++ b/docs/issues/ROADMAP.md @@ -54,7 +54,7 @@ Locked decisions: hybrid custody (approveAgent once, Privy-managed agent, trade- - [ ] #25 `leverage` command (cross/isolated) ### Skill & Docs -- [ ] #37 SKILL.md for Claude Code / Codex +- [x] #37 SKILL.md for Claude Code / Codex (live agent validation tracked in #39) - [ ] #38 README, command reference and docs site ### Packaging diff --git a/docs/testnet.md b/docs/testnet.md index 2dc1ea9..aa1fb3b 100644 --- a/docs/testnet.md +++ b/docs/testnet.md @@ -52,4 +52,6 @@ An AI-driven skill forward run remains a separate acceptance requirement: have a coding agent read the installed skill, use the dedicated testnet setup, follow its approval/funding boundaries, and record its agent/session ID plus lifecycle and journal evidence. The deterministic CI script is not represented as that agent -session. Without credentials and both forms of evidence, #37/#39 remain partial. +session. #37 covers the completed skill content, installation and hosting. Its +live-session criterion is now tracked in #39, which remains open until both forms +of live testnet evidence are recorded. diff --git a/packages/agent-cli/scripts/e2e-testnet.mjs b/packages/agent-cli/scripts/e2e-testnet.mjs index e1c914a..337ccff 100644 --- a/packages/agent-cli/scripts/e2e-testnet.mjs +++ b/packages/agent-cli/scripts/e2e-testnet.mjs @@ -18,7 +18,7 @@ const report = { privy: { mode: 'live dedicated test app', verified: false }, relay: { mode: 'mocked zero-value route; pre-funded collateral', verified: false }, }, - agentSession: { status: 'not-run', reason: 'Deterministic CI script; an independent coding-agent session is required for issue 37' }, + agentSession: { status: 'not-run', reason: 'Deterministic CI script; issue 39 tracks the independent coding-agent session transferred from issue 37' }, commit: process.env.GITHUB_SHA ?? null, workflowRun: process.env.GITHUB_RUN_ID ?? null, startedAt: new Date().toISOString(), stages: [], cleanup: 'not-started',