From ba369e5c62ee3998ce9121b9b06638e3fa217d47 Mon Sep 17 00:00:00 2001 From: Hanwen Cheng Date: Tue, 2 Jun 2026 17:54:46 +0800 Subject: [PATCH] docs: repoint dead development-stages.md links to v2 archive + milestone roadmap The 8-stage plan was archived to docs/archived/development-stages-v2-2026-04.md and docs/spec/plans/ no longer holds it; ~47 stale references across 16 files were broken. Repointed by context: - Historical stage content -> docs/archived/development-stages-v2-2026-04.md (42 refs: README, TODOS, threat-model, broker/operator guide, heima-gaps, post-v0.1, execution-plan, all wiki pages, and the CLI provision-error blob URLs in lib.rs + cli_tests.rs kept in sync). - Live 'current roadmap' pointers -> docs/spec/plans/milestones-roadmap.md (3 refs: README per-session protocol aligned to CLAUDE.md, arch.md, wiki Home roadmap row). arch.md uses the live roadmap rather than archived per the no-arch.md-links-to-archived rule. Also fixed the adjacent broken link in broker-and-operator-dev-guide.md: ./plans/issue-101-ci-auto-deploy.md (never existed) -> ../ci-setup.md. Left intentionally: execution-plan.md:5,157 'v2/plans/development-stages.md' are project-life SOURCE paths (the 759-line original), not in-repo links. Verified: markdown broken-relative-link scan shows 0 broken development-stages links and no new breakage (191->190); cargo check -p agentkeys-cli exits 0. --- README.md | 4 ++-- TODOS.md | 2 +- crates/agentkeys-cli/src/lib.rs | 12 ++++++------ crates/agentkeys-cli/tests/cli_tests.rs | 2 +- docs/arch.md | 2 +- docs/plan/execution-plan.md | 14 +++++++------- docs/spec/broker-and-operator-dev-guide.md | 4 ++-- docs/spec/heima-gaps-vs-desired-architecture.md | 2 +- docs/spec/post-v0.1-future-work.md | 4 ++-- docs/spec/threat-model-key-custody.md | 4 ++-- docs/wiki/Home.md | 4 ++-- docs/wiki/blockchain-tee-architecture.md | 10 +++++----- docs/wiki/hosted-first.md | 4 ++-- docs/wiki/key-security.md | 12 ++++++------ docs/wiki/overview.md | 4 ++-- docs/wiki/serve-and-audit.md | 8 ++++---- 16 files changed, 46 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 2d59ea8d..238a989b 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ Dual-licensed under **MIT OR Apache-2.0**, at your choice. |---|---| | [`CLAUDE.md`](CLAUDE.md) | Project-specific rules: docs layout, /create-pr workflow in worktrees, terminology-source-of-truth, branch push policy, idempotent-remote-setup invariants, runbook-fix-fold-back policy. **Read first, every session.** | | [`docs/arch.md`](docs/arch.md) | Single source of truth for component inventory (K1–K11), trust boundaries, HDKD actor tree, per-actor binding ceremonies. When the per-doc detail outgrows arch.md, link outward — never duplicate. | -| [`docs/spec/plans/development-stages.md`](docs/spec/plans/development-stages.md) | The 8-stage build plan. Each stage has a `harness/stage-N-done.sh` gate; never self-grade — run the gate. | +| [`docs/archived/development-stages-v2-2026-04.md`](docs/archived/development-stages-v2-2026-04.md) | The 8-stage build plan (archived; superseded by the milestone roadmap below). Each stage has a `harness/stage-N-done.sh` gate; never self-grade — run the gate. | | [`docs/plan/execution-plan.md`](docs/plan/execution-plan.md) | Orchestration runbook (ralph, team, ultraqa workflows). | | [`docs/spec/broker-and-operator-dev-guide.md`](docs/spec/broker-and-operator-dev-guide.md) | Inner edit-build-test loop for broker + operator-side code. Use this before suggesting changes to the broker's run-time behavior. | @@ -97,7 +97,7 @@ These are non-negotiable. Violating them produces broken PRs / corrupted state. ### Per-session protocol 1. `jj log --limit 10 && cat harness/progress.json && bash harness/init.sh $(jq -r .current_stage harness/progress.json)` -2. Read the stage contract for the current stage in `docs/spec/plans/development-stages.md`. +2. Read the milestone scope for the current milestone in `docs/plan/milestones-roadmap.md` (the v1/v2 stage framing is archived at `docs/archived/development-stages-v2-2026-04.md`). 3. Pick the HIGHEST-PRIORITY incomplete deliverable from `harness/features.json`. 4. Implement ONE deliverable, run `cargo test -p `, `jj describe`, update `harness/features.json`, `jj new`. diff --git a/TODOS.md b/TODOS.md index 15332224..2f6a896f 100644 --- a/TODOS.md +++ b/TODOS.md @@ -144,4 +144,4 @@ milestone. Filing as TODOs to prevent "post-MVP" from becoming "never": - Stage 5b: agentic fallback + audit trail + fallback→PR + `/agentkeys-record-scraper` skill usage - Stage 6: npm package + install.sh + README polish + DX docs - Stage 8: production hardening (daemon memory hygiene + CLI defensive features) -- Pattern 4 (Heima) audit submission infrastructure — see docs/spec/plans/development-stages.md Stage 9 +- Pattern 4 (Heima) audit submission infrastructure — see docs/archived/development-stages-v2-2026-04.md Stage 9 diff --git a/crates/agentkeys-cli/src/lib.rs b/crates/agentkeys-cli/src/lib.rs index 68eac918..d94f486b 100644 --- a/crates/agentkeys-cli/src/lib.rs +++ b/crates/agentkeys-cli/src/lib.rs @@ -1281,23 +1281,23 @@ pub async fn cmd_scope( fn format_provision_error(err: &ProvisionError) -> String { match err { ProvisionError::InProgress { active_service } => format!( - "Problem: Another provision is running for {}.\nCause: Provisioner serializes calls per daemon.\nFix: Wait and retry.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md", + "Problem: Another provision is running for {}.\nCause: Provisioner serializes calls per daemon.\nFix: Wait and retry.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md", active_service ), ProvisionError::Tripwire { kind, step, .. } => format!( - "Problem: A script step timed out at '{}'.\nCause: The target site's DOM may have changed (tripwire: {:?}).\nFix: Open an issue at https://github.com/litentry/agentKeys/issues with the logs.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md", + "Problem: A script step timed out at '{}'.\nCause: The target site's DOM may have changed (tripwire: {:?}).\nFix: Open an issue at https://github.com/litentry/agentKeys/issues with the logs.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md", step, kind ), ProvisionError::StoreFailed { obtained_key_masked, .. } => format!( - "Problem: Credential provisioned but storage failed.\nCause: Backend store_credential returned an error.\nFix: Manually store the key with `agentkeys store `. Masked key for reference: {}.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md", + "Problem: Credential provisioned but storage failed.\nCause: Backend store_credential returned an error.\nFix: Manually store the key with `agentkeys store `. Masked key for reference: {}.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md", obtained_key_masked ), ProvisionError::VerificationFailed { service, reason } => format!( - "Problem: Key verification failed for {}.\nCause: {}.\nFix: Re-run with --force to attempt a fresh provision.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md", + "Problem: Key verification failed for {}.\nCause: {}.\nFix: Re-run with --force to attempt a fresh provision.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md", service, reason ), other => format!( - "Problem: Provision failed.\nCause: {}.\nFix: Check logs and retry.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md", + "Problem: Provision failed.\nCause: {}.\nFix: Check logs and retry.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md", other ), } @@ -1339,7 +1339,7 @@ pub async fn cmd_provision( ], other => { return Err(anyhow!( - "Problem: Service '{}' not supported.\nCause: Only 'openrouter' is supported in Stage 5a.\nFix: Use a supported service name.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md", + "Problem: Service '{}' not supported.\nCause: Only 'openrouter' is supported in Stage 5a.\nFix: Use a supported service name.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md", other )); } diff --git a/crates/agentkeys-cli/tests/cli_tests.rs b/crates/agentkeys-cli/tests/cli_tests.rs index b56db7d9..3846d1cc 100644 --- a/crates/agentkeys-cli/tests/cli_tests.rs +++ b/crates/agentkeys-cli/tests/cli_tests.rs @@ -1552,7 +1552,7 @@ async fn cli_provision_error_format() { assert!(result.is_err()); match result.unwrap_err() { ProvisionError::InProgress { .. } => { - let formatted = "Problem: Another provision is running for openrouter.\nCause: Provisioner serializes calls per daemon.\nFix: Wait and retry.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/development-stages.md"; + let formatted = "Problem: Another provision is running for openrouter.\nCause: Provisioner serializes calls per daemon.\nFix: Wait and retry.\nDocs: https://github.com/litentry/agentKeys/blob/main/docs/archived/development-stages-v2-2026-04.md"; assert!( formatted.contains("Problem:"), "missing Problem: in: {formatted}" diff --git a/docs/arch.md b/docs/arch.md index dffa68f0..39c37271 100644 --- a/docs/arch.md +++ b/docs/arch.md @@ -2264,7 +2264,7 @@ The full bring-up runbook lives in [`scripts/setup-broker-host.sh`](../scripts/s - **Per-endpoint request/response shapes.** Each endpoint surface has its own canonical doc — broker endpoints in `plan/v2-issues/issue-v2-stage-1-foundation.md`; signer in `signer-protocol.md`; workers in per-worker READMEs under each crate. - **Per-step environment-variable inventory.** That's `operator-runbook.md`. - **Detailed threat model for K3 retroactive confidentiality.** That's `threat-model-key-custody.md`. -- **Stage-by-stage build progression history.** That's `plans/development-stages.md` + `plan/v2-issues/`. +- **Stage-by-stage build progression history.** That's `plan/milestones-roadmap.md` §1 (Phase 0, which links onward to the archived stage plan) + `plan/v2-issues/`. - **MetaMask / Foundry tooling instructions.** Retired in v2 — operators no longer hold local EVM keys unless they want to (`identity_type = evm` is supported but not required). - **v3+ hardening** (per-(user, service) KEK, wrap-and-rewrap, ZK-proven cap minting, threshold-MPC signer, per-operator K3) — tracked separately as v3+ issues. v2 ships the design described here. diff --git a/docs/plan/execution-plan.md b/docs/plan/execution-plan.md index 7d1a94f0..7fd53b84 100644 --- a/docs/plan/execution-plan.md +++ b/docs/plan/execution-plan.md @@ -34,7 +34,7 @@ Then create `CLAUDE.md` in the repo root encoding the harness workflow (read pro **Invoke:** ``` -/oh-my-claudecode:ralph "Implement Stage 0 per docs/spec/plans/development-stages.md: create Cargo workspace skeleton (7 crates), harness artifacts (init.sh, progress.json, features.json, stage-0-done.sh), agentkeys-types crate (all types from docs/spec/credential-backend-interface.md), agentkeys-core crate (CredentialBackend trait with 15 methods, PaymentRail trait, canonical CBOR serialization, OTP derivation, test vectors). 8 tests must pass. Tag stage-0-done when done." +/oh-my-claudecode:ralph "Implement Stage 0 per docs/archived/development-stages-v2-2026-04.md: create Cargo workspace skeleton (7 crates), harness artifacts (init.sh, progress.json, features.json, stage-0-done.sh), agentkeys-types crate (all types from docs/spec/credential-backend-interface.md), agentkeys-core crate (CredentialBackend trait with 15 methods, PaymentRail trait, canonical CBOR serialization, OTP derivation, test vectors). 8 tests must pass. Tag stage-0-done when done." ``` **Deliverables:** Cargo workspace compiles, 8 tests pass, harness artifacts exist, `bash harness/stage-0-done.sh` exits 0. @@ -47,7 +47,7 @@ The largest stage: 37 tests, 10 stories. Ralph loops through them. **Invoke:** ``` -/oh-my-claudecode:ralph "Implement Stage 1 per docs/spec/plans/development-stages.md: agentkeys-mock-server (axum + rusqlite) with 7 SQLite tables, 15 REST endpoints implementing every CredentialBackend method, identity linking, master key custody, TTL/single-use enforcement, MockHttpClient connection. 37 tests must pass. See docs/archived/eng-review-test-plan.md for the full test matrix including property tests (pair-code collision, nonce uniqueness) and integrity tests (tamper detection, OTP replay). Tag stage-1-done when done." +/oh-my-claudecode:ralph "Implement Stage 1 per docs/archived/development-stages-v2-2026-04.md: agentkeys-mock-server (axum + rusqlite) with 7 SQLite tables, 15 REST endpoints implementing every CredentialBackend method, identity linking, master key custody, TTL/single-use enforcement, MockHttpClient connection. 37 tests must pass. See docs/archived/eng-review-test-plan.md for the full test matrix including property tests (pair-code collision, nonce uniqueness) and integrity tests (tamper detection, OTP replay). Tag stage-1-done when done." ``` **Deliverables:** Mock server starts on port 8090, all 37 tests pass, curl smoke test works, `bash harness/stage-1-done.sh` exits 0. @@ -60,7 +60,7 @@ The one parallelization opportunity. Stages 2 (CLI, 14 tests) and 3 (Daemon+MCP, **Invoke:** ``` -/oh-my-claudecode:team 2:executor "Two parallel stages for AgentKeys. AGENT 1: Implement Stage 2 (CLI Core) per docs/spec/plans/development-stages.md — 10 CLI commands in agentkeys-cli, 14 tests, keyring session storage, error messaging spec, --help with examples. AGENT 2: Implement Stage 3 (Daemon + MCP) per docs/spec/plans/development-stages.md — agentkeys-daemon binary with MCP tools (get_credential, list_credentials), kernel hardening (memfd_secret, seccomp, caps), 13 tests. Use AGENTKEYS_SESSION env var as test seam (NOT the production bootstrap). Both agents: read harness/progress.json first, commit per deliverable, tag stage-N-done when complete." +/oh-my-claudecode:team 2:executor "Two parallel stages for AgentKeys. AGENT 1: Implement Stage 2 (CLI Core) per docs/archived/development-stages-v2-2026-04.md — 10 CLI commands in agentkeys-cli, 14 tests, keyring session storage, error messaging spec, --help with examples. AGENT 2: Implement Stage 3 (Daemon + MCP) per docs/archived/development-stages-v2-2026-04.md — agentkeys-daemon binary with MCP tools (get_credential, list_credentials), kernel hardening (memfd_secret, seccomp, caps), 13 tests. Use AGENTKEYS_SESSION env var as test seam (NOT the production bootstrap). Both agents: read harness/progress.json first, commit per deliverable, tag stage-N-done when complete." ``` **Deliverables:** Both `stage-2-done.sh` and `stage-3-done.sh` exit 0. `cargo test --workspace` passes all 72 tests (8+37+14+13). @@ -73,7 +73,7 @@ The cross-component integration stage. Modifies both daemon (pair-on-startup) an **Invoke:** ``` -/oh-my-claudecode:ralph "Implement Stage 4 per docs/spec/plans/development-stages.md: child-initiates rendezvous pairing (daemon generates keypair → open_auth_request → register_rendezvous → display pair code → long-poll), CLI approve command (fetch_auth_request → display OTP → user confirms → approve_auth_request), recovery flow (--recover with AgentIdentity resolution via identity graph). 11 tests must pass. Two-terminal pair E2E must work. Tag stage-4-done." +/oh-my-claudecode:ralph "Implement Stage 4 per docs/archived/development-stages-v2-2026-04.md: child-initiates rendezvous pairing (daemon generates keypair → open_auth_request → register_rendezvous → display pair code → long-poll), CLI approve command (fetch_auth_request → display OTP → user confirms → approve_auth_request), recovery flow (--recover with AgentIdentity resolution via identity graph). 11 tests must pass. Two-terminal pair E2E must work. Tag stage-4-done." ``` **Deliverables:** Pair flow works across two terminals, recovery preserves credentials, 11 tests pass. @@ -86,7 +86,7 @@ Mixed Rust+TypeScript stage. Playwright browser automation for OpenRouter signup **Invoke:** ``` -/oh-my-claudecode:ralph "Implement Stage 5 per docs/spec/plans/development-stages.md: agentkeys-provisioner Rust orchestrator (spawn TS subprocess, IPC via stdin/stdout JSON, encrypt API key to shielding key, store_credential), provisioner-scripts/lib/email.ts (Gmail IMAP plus-addressing for verification codes), provisioner-scripts/scrapers/openrouter.ts (Playwright signup flow using email.ts). MCP tool: agentkeys.provision(service). 9 tests must pass. Tag stage-5-done." +/oh-my-claudecode:ralph "Implement Stage 5 per docs/archived/development-stages-v2-2026-04.md: agentkeys-provisioner Rust orchestrator (spawn TS subprocess, IPC via stdin/stdout JSON, encrypt API key to shielding key, store_credential), provisioner-scripts/lib/email.ts (Gmail IMAP plus-addressing for verification codes), provisioner-scripts/scrapers/openrouter.ts (Playwright signup flow using email.ts). MCP tool: agentkeys.provision(service). 9 tests must pass. Tag stage-5-done." ``` **Deliverables:** Orchestrator IPC tests pass, email client tests pass, live OpenRouter provision works (manual verification by human). @@ -99,7 +99,7 @@ Packaging and documentation polish. **Invoke:** ``` -/oh-my-claudecode:ralph "Implement Stage 6 per docs/spec/plans/development-stages.md: @agentkeys/daemon npm package with postinstall binary selection (linux-x64, linux-arm64, darwin-x64, darwin-arm64), install.sh curl script, README with quickstart, docs/how-it-works.md, docs/security-model.md, CHANGELOG, LICENSE (MIT OR Apache-2.0), per-subcommand --help with examples. 7 tests must pass. Tag stage-6-done." +/oh-my-claudecode:ralph "Implement Stage 6 per docs/archived/development-stages-v2-2026-04.md: @agentkeys/daemon npm package with postinstall binary selection (linux-x64, linux-arm64, darwin-x64, darwin-arm64), install.sh curl script, README with quickstart, docs/how-it-works.md, docs/security-model.md, CHANGELOG, LICENSE (MIT OR Apache-2.0), per-subcommand --help with examples. 7 tests must pass. Tag stage-6-done." ``` **Advance:** `bash harness/advance-stage.sh 6 7` @@ -133,7 +133,7 @@ bash harness/advance-stage.sh N N+1 # advance to next stage |---|---| | Ralph session dies mid-story | Re-invoke `/ralph` with same PRD. Ralph reads progress.json + git log and resumes from last completed story. | | One team agent fails, other succeeds | Invoke `/ralph` individually for the failed stage. The successful stage's work is already committed. | -| Test seems like a spec bug | `credential-backend-interface.md` > `development-stages.md` > `eng-review-test-plan.md` (priority order). Fix spec if genuinely wrong, then re-run. | +| Test seems like a spec bug | `credential-backend-interface.md` > `development-stages-v2-2026-04.md` > `eng-review-test-plan.md` (priority order). Fix spec if genuinely wrong, then re-run. | | Playwright breaks on live site | Update selectors in `openrouter.ts`. Rust IPC tests still pass (mock subprocess). | | Stage 7 E2E keeps failing after 5 ultraqa cycles | Human diagnoses root cause. Likely a cross-component integration issue that needs manual architectural judgment. | diff --git a/docs/spec/broker-and-operator-dev-guide.md b/docs/spec/broker-and-operator-dev-guide.md index 88dcae8d..6333dad6 100644 --- a/docs/spec/broker-and-operator-dev-guide.md +++ b/docs/spec/broker-and-operator-dev-guide.md @@ -195,7 +195,7 @@ When you don't want to talk to Heima at all, run [foundry](https://book.getfound anvil --chain-id 31337 --port 8545 ``` -Then `AGENTKEYS_CHAIN=anvil` in your operator env makes every `cast send` hit anvil instead of Heima. The deployer wallet is whichever anvil-prefunded key you point at via `HEIMA_DEPLOYER_KEY` / `HEIMA_DEPLOYER_KEY_FILE`. Anvil's mempool is single-tenant — none of the [PR #102 nonce-contention issues](./plans/issue-101-ci-auto-deploy.md) bite locally. +Then `AGENTKEYS_CHAIN=anvil` in your operator env makes every `cast send` hit anvil instead of Heima. The deployer wallet is whichever anvil-prefunded key you point at via `HEIMA_DEPLOYER_KEY` / `HEIMA_DEPLOYER_KEY_FILE`. Anvil's mempool is single-tenant — none of the [PR #102 nonce-contention issues](../ci-setup.md) bite locally. ### 4.4 Editing `setup-broker-host.sh` @@ -333,4 +333,4 @@ Switch with `--chain` on any harness script. Contract addresses for `heima` and - [`docs/ci-setup.md`](../ci-setup.md) — no-LLM CI + auto-deploy of test broker (issue #101 / PR #102). - [`docs/spec/signer-protocol.md`](./signer-protocol.md) — wire contract for the signer (TEE swap-in target). - [`docs/spec/credential-backend-interface.md`](./credential-backend-interface.md) — the `CredentialBackend` trait; what the broker's storage plug-ins must implement. -- [`docs/spec/plans/development-stages.md`](./plans/development-stages.md) — the staged build plan + harness gates. +- [`docs/archived/development-stages-v2-2026-04.md`](../archived/development-stages-v2-2026-04.md) — the staged build plan + harness gates. diff --git a/docs/spec/heima-gaps-vs-desired-architecture.md b/docs/spec/heima-gaps-vs-desired-architecture.md index 502ddc65..12acbe31 100644 --- a/docs/spec/heima-gaps-vs-desired-architecture.md +++ b/docs/spec/heima-gaps-vs-desired-architecture.md @@ -24,7 +24,7 @@ Related docs: - [`plans/issue-74-step-1c-device-key-auth.md`](../plan/issue-74-step-1c-device-key-auth.md) — device-key auth on `/dev/*`, planned. - [`docs/wiki/blockchain-tee-architecture.md`](../wiki/blockchain-tee-architecture.md) — canonical desired architecture (four rules). - [`docs/wiki/key-security.md`](../wiki/key-security.md) — TEE key security model. -- [`plans/development-stages.md`](./plans/development-stages.md) — stage roadmap; this gap list is the critical path for Stage 6 and Stage 7. +- [`development-stages-v2-2026-04.md`](../archived/development-stages-v2-2026-04.md) — stage roadmap (archived); this gap list is the critical path for Stage 6 and Stage 7. - [`ses-email-architecture.md`](./ses-email-architecture.md) — Stage 6 email spec; depends on gaps §2, §3, §5. ## 1a. Status snapshot (added 2026-05-09) diff --git a/docs/spec/post-v0.1-future-work.md b/docs/spec/post-v0.1-future-work.md index 0924a9d9..54ad7ffb 100644 --- a/docs/spec/post-v0.1-future-work.md +++ b/docs/spec/post-v0.1-future-work.md @@ -1,12 +1,12 @@ # Post-v0.1 Future Work **Status:** living backlog — items deferred past v0.1. -**Purpose:** capture design directions, hardening work, and extensions that are valuable but not on the v0 or v0.1 critical path. Every item here should eventually be promoted to `docs/spec/plans/development-stages.md` with a concrete stage number, or dropped. +**Purpose:** capture design directions, hardening work, and extensions that are valuable but not on the v0 or v0.1 critical path. Every item here should eventually be promoted to `docs/archived/development-stages-v2-2026-04.md` with a concrete stage number, or dropped. **Last updated:** 2026-04-20. ## 1. How this doc relates to the stage plan -- [`docs/spec/plans/development-stages.md`](./plans/development-stages.md) — the stages we are committed to shipping. +- [`docs/archived/development-stages-v2-2026-04.md`](../archived/development-stages-v2-2026-04.md) — the stages we are committed to shipping. - [`docs/spec/heima-gaps-vs-desired-architecture.md`](./heima-gaps-vs-desired-architecture.md) — deltas between upstream `litentry/heima` and the desired architecture; blockers for current stages. - **This doc** — ideas that do not block current stages. Items here come from design reviews where we identified a better-but-bigger option, deferred it, and shipped the cheap version. diff --git a/docs/spec/threat-model-key-custody.md b/docs/spec/threat-model-key-custody.md index ede9489e..101d5707 100644 --- a/docs/spec/threat-model-key-custody.md +++ b/docs/spec/threat-model-key-custody.md @@ -238,8 +238,8 @@ These do not block adopting the position in §6 but need decisions before Stage | [`docs/docs/wiki/data-classification.md`](../docs/wiki/data-classification.md) §1 row "Credential blobs" | "On chain: Encrypted (ciphertext)" | "On chain: Hash + pointer; In TEE: per-request decrypt only; Off-chain S3: ciphertext under per-epoch DEK" | | [`docs/docs/wiki/key-security.md`](../docs/wiki/key-security.md) §1 table | "v0.1 Heima: Encrypted blob in Heima TEE (`pallet-secrets-vault`)" | "v0.1 (Stage 8): off-chain S3 ciphertext under per-epoch DEK; chain holds pointer + hash" | | [`docs/spec/credential-backend-interface.md`](./credential-backend-interface.md) §"Mapping to Heima Primitives" | `store_credential` → `pallet-secrets-vault::write_secret` | `store_credential` → S3 write + on-chain `pallet-vault-pointers` extrinsic | -| [`docs/spec/plans/development-stages.md`](./plans/development-stages.md) Stage 8 (current) | "Production hardening — memory hygiene" | Renumbered to **Stage 9**; new **Stage 8 = off-chain encrypted vault** (this doc's position) | -| [`docs/spec/plans/development-stages.md`](./plans/development-stages.md) Stage 9 (current) | "Heima migration holding pen" | Renumbered to **Stage 10** | +| [`docs/archived/development-stages-v2-2026-04.md`](../archived/development-stages-v2-2026-04.md) Stage 8 (current) | "Production hardening — memory hygiene" | Renumbered to **Stage 9**; new **Stage 8 = off-chain encrypted vault** (this doc's position) | +| [`docs/archived/development-stages-v2-2026-04.md`](../archived/development-stages-v2-2026-04.md) Stage 9 (current) | "Heima migration holding pen" | Renumbered to **Stage 10** | --- diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 509ddb3d..164e15fc 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -50,7 +50,7 @@ Design docs for specific services built on top of the foundations: | Role | Start here | Then | Then | |---|---|---|---| | New engineer | [Blockchain TEE Architecture](blockchain-tee-architecture) | [Session Token](session-token) | [Email System](email-system) | -| Product / roadmap | This page, §Wiki tree | `docs/spec/plans/development-stages.md` | [Hosted-First](hosted-first) | +| Product / roadmap | This page, §Wiki tree | `docs/plan/milestones-roadmap.md` | [Hosted-First](hosted-first) | | Operator / infra | [Key Security](key-security), [Serve and Audit](serve-and-audit) | `docs/spec/ses-email-architecture.md` | [OIDC Federation](oidc-federation) §Consumer-registration recipes | | Security reviewer | [Blockchain TEE Architecture](blockchain-tee-architecture) §6 (four rules) | [Data Classification](data-classification) | [Tag-Based Access](tag-based-access) §Security and attacker surface | @@ -60,7 +60,7 @@ Design docs for specific services built on top of the foundations: Canonical design records live in `docs/spec/`: -- **`docs/spec/plans/development-stages.md`** — build plan. Stages 0–5 shipped; **Stage 6 = federated own email**; **Stage 7 = generalized OIDC provider**; remaining stages postponed. +- **`docs/archived/development-stages-v2-2026-04.md`** — build plan (archived). Stages 0–5 shipped; **Stage 6 = federated own email**; **Stage 7 = generalized OIDC provider**; remaining stages postponed. - **`docs/spec/ses-email-architecture.md`** — Stage 6 SES email spec. - **`docs/spec/email-signing-backends.md`** — generalized backend comparison (SES / DWD / SaaS). - **`docs/spec/credential-backend-interface.md`** — the `CredentialBackend` trait. diff --git a/docs/wiki/blockchain-tee-architecture.md b/docs/wiki/blockchain-tee-architecture.md index 3bd2701b..2bebdb70 100644 --- a/docs/wiki/blockchain-tee-architecture.md +++ b/docs/wiki/blockchain-tee-architecture.md @@ -135,7 +135,7 @@ The core pattern: **clients talk to the TEE, the TEE talks to the chain.** Clien ## 2. Worked example: credential retrieval -> **Status:** this example shows the **v0.1** flow (Pattern 4: TEE-as-paymaster per-read sponsored audit). v0 uses the mock backend with a synchronous SQLite audit insert — see `docs/spec/plans/development-stages.md` Stage 1 for the v0 implementation. Pattern 4 is tracked in [#5](https://github.com/litentry/agentKeys/issues/5). +> **Status:** this example shows the **v0.1** flow (Pattern 4: TEE-as-paymaster per-read sponsored audit). v0 uses the mock backend with a synchronous SQLite audit insert — see `docs/archived/development-stages-v2-2026-04.md` Stage 1 for the v0 implementation. Pattern 4 is tracked in [#5](https://github.com/litentry/agentKeys/issues/5). This is the most common operation. An agent daemon needs an API key to call OpenRouter. @@ -196,9 +196,9 @@ This is the most common operation. An agent daemon needs an API key to call Open ## 3. Worked example: pairing (on-chain transport — v0.1 target) -> **Status:** this example shows the **v0.1** on-chain pair transport. v0 uses a centralized rendezvous relay (SQLite `rendezvous_registrations` + `auth_requests` tables, 6 REST endpoints) — see `docs/spec/plans/development-stages.md` Stage 1 for the v0 implementation. The v0.1 migration is tracked in [#6](https://github.com/litentry/agentKeys/issues/6). +> **Status:** this example shows the **v0.1** on-chain pair transport. v0 uses a centralized rendezvous relay (SQLite `rendezvous_registrations` + `auth_requests` tables, 6 REST endpoints) — see `docs/archived/development-stages-v2-2026-04.md` Stage 1 for the v0 implementation. The v0.1 migration is tracked in [#6](https://github.com/litentry/agentKeys/issues/6). -A new daemon in a sandbox wants to pair with the master user's wallet. This is the on-chain pair design from `[docs/spec/plans/development-stages.md](../spec/plans/development-stages.md)` Stage 9. +A new daemon in a sandbox wants to pair with the master user's wallet. This is the on-chain pair design from `[docs/archived/development-stages-v2-2026-04.md](../archived/development-stages-v2-2026-04.md)` Stage 9. ### Step-by-step @@ -322,7 +322,7 @@ The pair flow uses two distinct human-verification codes at different stages of | Server-validated? | Yes — stored in `auth_requests` table, single-use enforced | No — server holds no OTP state; any client derives the same VVC from the same signature | | Threat it defends against | Tampered request details between `open` and `approve` (canonical-hash mismatch rejects the approval) | Decoy pair requests on-chain — multiple pending pairs look the same, VVC lets the user visually tiebreak | | Shipped in | v0 mock backend (current code) | v0.1 on-chain pair transport (not yet implemented) | -| Referenced in | `development-stages.md` Stages 0, 1, 4; `otp::determinism` test | `development-stages.md` Stage 9; [#6](https://github.com/litentry/agentKeys/issues/6) | +| Referenced in | `development-stages-v2-2026-04.md` Stages 0, 1, 4; `otp::determinism` test | `development-stages-v2-2026-04.md` Stage 9; [#6](https://github.com/litentry/agentKeys/issues/6) | v0.1 does **not** keep OTP: with on-chain pair transport, there is no `auth_requests` table to hold nonces, and tamper detection comes from extrinsic signature verification at the pallet level. VVC replaces OTP as the human-visible code; the security property (protect against request-detail tampering and decoy daemons) shifts from OTP's HMAC-of-details to the pallet's signature check + VVC's signature-fingerprint comparison. @@ -636,7 +636,7 @@ Narrower surfaces with their own dedicated pages: - `[docs/spec/heima-cli-exploration.md](../spec/heima-cli-exploration.md)` — per-call signing, audit-as-extrinsic, latency acknowledgement - `[docs/spec/heima-open-questions.md](../spec/heima-open-questions.md)` — Q1 (scoped session minting), Q3 (TEE-side scope enforcement), Q9 (revocation latency) - `[docs/spec/credential-backend-interface.md](../spec/credential-backend-interface.md)` — CredentialBackend trait, signing model, payment rails -- `[docs/spec/plans/development-stages.md](../spec/plans/development-stages.md)` — Stage 9 design decisions (Pattern 4, on-chain pair transport) +- `[docs/archived/development-stages-v2-2026-04.md](../archived/development-stages-v2-2026-04.md)` — Stage 9 design decisions (Pattern 4, on-chain pair transport) ### Wiki diff --git a/docs/wiki/hosted-first.md b/docs/wiki/hosted-first.md index 043ae11a..aab4e8af 100644 --- a/docs/wiki/hosted-first.md +++ b/docs/wiki/hosted-first.md @@ -221,7 +221,7 @@ The tradeoff is correct for the user segment: non-dev users accept "trust AgentK - **Stage 7** — Generalized OIDC Provider: the federation pattern exposed publicly; accepts external consumers; enables the BYO AWS / GCP / GitHub / etc. advanced paths. - **Later** — BYO custom-domain email, BYO Workspace DWD (existing `docs/stage5-workspace-email-setup.md` becomes the runbook), BYO GitHub org, enterprise SSO integration. -See `docs/spec/plans/development-stages.md` for the authoritative stage list. +See `docs/archived/development-stages-v2-2026-04.md` for the authoritative stage list. --- @@ -234,5 +234,5 @@ See `docs/spec/plans/development-stages.md` for the authoritative stage list. - `docs/spec/ses-email-architecture.md` — spec for the SES-backed hosted path - `docs/stage5-workspace-email-setup.md` — the BYO Workspace runbook (advanced, deferred) - `wiki/blockchain-tee-architecture.md` (repo) — the three rules hosted-first preserves -- `docs/spec/plans/development-stages.md` §Stage 6 — federated own email stage plan +- `docs/archived/development-stages-v2-2026-04.md` §Stage 6 — federated own email stage plan diff --git a/docs/wiki/key-security.md b/docs/wiki/key-security.md index a315e4f9..84090cd2 100644 --- a/docs/wiki/key-security.md +++ b/docs/wiki/key-security.md @@ -271,7 +271,7 @@ The two surfaces need two different mitigation layers, and they map directly to ### Layer 1 — Kernel hardening (already planned in Stage 3) -`docs/spec/plans/development-stages.md:351-358` and `docs/arch.md:70` already specify the kernel-level defenses. They are required deliverables for Stage 3 (the daemon stage), with passing tests gating stage completion. Reproduced here for reference: +`docs/archived/development-stages-v2-2026-04.md` and `docs/arch.md:70` already specify the kernel-level defenses. They are required deliverables for Stage 3 (the daemon stage), with passing tests gating stage completion. Reproduced here for reference: | Feature | What it blocks | Verified by | @@ -289,7 +289,7 @@ This is **all kernel-side**. It assumes the daemon's own code is well-behaved an ### Layer 2 — Memory hygiene and credential lifecycle (planned in Stage 8) -`docs/spec/plans/development-stages.md` Stage 8 (added after this Stage 4 investigation) covers the process-internal hardening. **Priority A items shrink the dominant exposure window — the agent-side window — not the daemon window.** This is the corrected framing after the Stage 4 review caught the original ranking inverting these. +`docs/archived/development-stages-v2-2026-04.md` Stage 8 (added after this Stage 4 investigation) covers the process-internal hardening. **Priority A items shrink the dominant exposure window — the agent-side window — not the daemon window.** This is the corrected framing after the Stage 4 review caught the original ranking inverting these. | Priority A item | What it blocks | Verified by | @@ -313,7 +313,7 @@ This is **all kernel-side**. It assumes the daemon's own code is well-behaved an **Priority C items** are reserved for v0.2+ generalizations: extending `memfd_secret`-via-SCM_RIGHTS to upstream agent runtimes that don't currently support fd-based credential reads, and generalizing daemon-mediated `cmd_run` to arbitrary parent processes. Both require runtime cooperation that we can't unilaterally provide. -See `docs/spec/plans/development-stages.md` Stage 8 section for the full breakdown, the unit test matrix, and the reviewer E2E checklist. +See `docs/archived/development-stages-v2-2026-04.md` Stage 8 section for the full breakdown, the unit test matrix, and the reviewer E2E checklist. ### Where the credential actually lives @@ -368,11 +368,11 @@ These are server-side properties that survive even when the user's machine is co ## 9. Hardening features and where they live in the plan -Every hardening item raised by this investigation has been mapped to a concrete stage in `docs/spec/plans/development-stages.md`. None of these are floating ideas anymore — they are all in either Stage 3 (kernel-level, daemon-only, already planned) or Stage 8 (memory hygiene + CLI features + storage options, added during this Stage 4 investigation). +Every hardening item raised by this investigation has been mapped to a concrete stage in `docs/archived/development-stages-v2-2026-04.md`. None of these are floating ideas anymore — they are all in either Stage 3 (kernel-level, daemon-only, already planned) or Stage 8 (memory hygiene + CLI features + storage options, added during this Stage 4 investigation). ### Already in Stage 3 (kernel hardening, daemon) -These were in the spec from day one and gate Stage 3 completion. Reproduced from `development-stages.md:351-358`: +These were in the spec from day one and gate Stage 3 completion. Reproduced from `development-stages-v2-2026-04.md`: - `memfd_secret()` for runtime session key copy (fallback to `mlock2` if `ENOSYS`) - `mlock2(MCL_CURRENT|MCL_FUTURE)` to prevent swap @@ -452,7 +452,7 @@ Sketch: - **Estimated effort:** 4-6 days - **Position in critical path:** Off the critical path. Stage 8 ships after the v0 demo (Stage 7) and does not block any earlier stage. Recommended sequencing: ship v0 from Stage 7, then immediately roll into Stage 8 before broad deployment. -See `docs/spec/plans/development-stages.md` Stage 8 section for the full deliverable list, unit test matrix, and reviewer E2E checklist. +See `docs/archived/development-stages-v2-2026-04.md` Stage 8 section for the full deliverable list, unit test matrix, and reviewer E2E checklist. --- diff --git a/docs/wiki/overview.md b/docs/wiki/overview.md index 14e3a4b4..c8955acf 100644 --- a/docs/wiki/overview.md +++ b/docs/wiki/overview.md @@ -77,7 +77,7 @@ AgentKeys wiki | If you're a… | Start with | Then | Then | |---|---|---|---| | New engineer on the team | `wiki/blockchain-tee-architecture.md` (repo) | [hosted-first](hosted-first) | [email-system](email-system) | -| Product / roadmap reviewer | [hosted-first](hosted-first) | `docs/spec/plans/development-stages.md` §Stage 5–7 roadmap update | [knowledge-storage](knowledge-storage) | +| Product / roadmap reviewer | [hosted-first](hosted-first) | `docs/archived/development-stages-v2-2026-04.md` §Stage 5–7 roadmap update | [knowledge-storage](knowledge-storage) | | Operator / infra setup | `docs/spec/ses-email-architecture.md` | [oidc-federation](oidc-federation) §Consumer-registration recipes | [tag-based-access](tag-based-access) §Concrete AWS configuration | | Security reviewer | `wiki/blockchain-tee-architecture.md` (repo) | [tag-based-access](tag-based-access) §Security properties and attacker surface | [oidc-federation](oidc-federation) §Threat model | @@ -105,7 +105,7 @@ Living in `docs/spec/`: | `ses-email-architecture.md` | The SES-backed email backend (v0.1 default on `agentkeys-email.io`) | | `email-signing-backends.md` | Generalized backend comparison (SES / DWD / AgentMail-style SaaS) | | `credential-backend-interface.md` | The `CredentialBackend` trait that every backend implements | -| `plans/development-stages.md` | The stage roadmap (Stages 0–5 shipped; Stage 6 = hosted email; Stage 7 = OIDC provider) | +| `../archived/development-stages-v2-2026-04.md` | The stage roadmap (archived; Stages 0–5 shipped; Stage 6 = hosted email; Stage 7 = OIDC provider) | And operator-facing docs: diff --git a/docs/wiki/serve-and-audit.md b/docs/wiki/serve-and-audit.md index 11f89bf9..f0b569a7 100644 --- a/docs/wiki/serve-and-audit.md +++ b/docs/wiki/serve-and-audit.md @@ -370,7 +370,7 @@ The TEE signs the audit extrinsic with the user's wallet key, and fees are debit ### Why Option A for v0.1 -The chosen option (A) minimizes Heima-side work and matches the hosted-AgentKeys business model. Options B and C remain open for future reconsideration as the product matures. See `[docs/spec/plans/development-stages.md](../spec/plans/development-stages.md)` Stage 9 for the full decision record. +The chosen option (A) minimizes Heima-side work and matches the hosted-AgentKeys business model. Options B and C remain open for future reconsideration as the product matures. See `[docs/archived/development-stages-v2-2026-04.md](../archived/development-stages-v2-2026-04.md)` Stage 9 for the full decision record. --- @@ -407,7 +407,7 @@ Full design: [issue #4](https://github.com/litentry/agentKeys/issues/4). ## 9. Deferred decisions -From the Stage 9 notes in `[docs/spec/plans/development-stages.md](../spec/plans/development-stages.md)`, three things need explicit design work before Pattern 4 implementation starts: +From the Stage 9 notes in `[docs/archived/development-stages-v2-2026-04.md](../archived/development-stages-v2-2026-04.md)`, three things need explicit design work before Pattern 4 implementation starts: ### 9.1 Cross-pattern mixing: `--sync-audit` opt-out @@ -453,7 +453,7 @@ Each has different durability-availability tradeoffs. **Decision deferred** unti - ⏳ **Rate limit ([issue #4](https://github.com/litentry/agentKeys/issues/4))** — must land in v0 mock backend as well as v0.1 TEE, prerequisite for Pattern 4 - ⏳ **Pattern 4 ([issue #5](https://github.com/litentry/agentKeys/issues/5))** — TEE-side paymaster integration, decoupled serve/audit code path, failure handling strategy (deferred decisions above) -- ⏳ **Stage 9 design decisions** captured in `[docs/spec/plans/development-stages.md](../spec/plans/development-stages.md)` as a holding pen until v0.1 migration work begins +- ⏳ **Stage 9 design decisions** captured in `[docs/archived/development-stages-v2-2026-04.md](../archived/development-stages-v2-2026-04.md)` as a holding pen until v0.1 migration work begins ### v0.2+ (future) @@ -491,7 +491,7 @@ The ~50ms target assumes Heima TEE is co-located with the daemon's network reach - `[docs/spec/1-step-analysis.md](../spec/1-step-analysis.md)` — auth layer design, `pallet-bitacross` pattern for TEE-held wallet keys - `[docs/spec/heima-cli-exploration.md](../spec/heima-cli-exploration.md)` — audit-as-extrinsic design (line 85), latency acknowledgement (line 116) - `[docs/spec/heima-open-questions.md](../spec/heima-open-questions.md)` — open questions for Kai including paymaster feasibility -- `[docs/spec/plans/development-stages.md](../spec/plans/development-stages.md)` — Stage 9 design decisions for Pattern 4, Option A fee funding, rate limit rationale +- `[docs/archived/development-stages-v2-2026-04.md](../archived/development-stages-v2-2026-04.md)` — Stage 9 design decisions for Pattern 4, Option A fee funding, rate limit rationale - `[wiki/key-security.md](./key-security.md)` — companion doc on the broader security architecture ### Source