From b9bd807d868f6ac55478340a77bdde16656fec5c Mon Sep 17 00:00:00 2001 From: TerminallyLazy Date: Tue, 25 Aug 2026 17:22:28 -0400 Subject: [PATCH 1/2] feat: add verified bootstrap and update guidance --- .codex-plugin/plugin.json | 6 +-- .github/workflows/hol-plugin-scanner.yml | 2 +- .github/workflows/validate.yml | 10 ++-- README.md | 36 ++++++++----- SUBMISSION.md | 27 +++++----- scripts/{smoke_v014.sh => smoke_v015.sh} | 4 +- scripts/validate-plugin.sh | 12 +++-- skills/tree-ring-memory/SKILL.md | 68 +++++++++++++++--------- 8 files changed, 96 insertions(+), 69 deletions(-) rename scripts/{smoke_v014.sh => smoke_v015.sh} (98%) diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index a5417f5..16d4add 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "tree-ring-memory", - "version": "0.3.2", - "description": "Local-first memory lifecycle and receipt-backed harness guidance for coding agents using Tree Ring Memory v0.14+.", + "version": "0.3.3", + "description": "Local-first memory lifecycle, project bootstrap, and receipt-backed harness guidance for coding agents using Tree Ring Memory v0.15+.", "author": { "name": "TerminallyLazy", "url": "https://github.com/TerminallyLazy" @@ -25,7 +25,7 @@ "interface": { "displayName": "Tree Ring Memory", "shortDescription": "Local-first memory lifecycle guidance for Codex agents.", - "longDescription": "Tree Ring Memory gives coding agents a lifecycle-aware practice for project recall, durable decisions, receipt-backed harness readiness, same-host fan-out/fan-in, idempotent worker writes, coordinator-authorized shared publication, explicit forgetting, and privacy-safe memory capture using Tree Ring Memory v0.14 or newer.", + "longDescription": "Tree Ring Memory gives coding agents a lifecycle-aware practice for verified project-local setup, project recall, durable decisions, receipt-backed harness readiness, same-host fan-out/fan-in, idempotent worker writes, coordinator-authorized shared publication, explicit forgetting, privacy-safe memory capture, and scope-preserving CLI updates using Tree Ring Memory v0.15 or newer.", "developerName": "TerminallyLazy", "category": "Developer Tools", "capabilities": [ diff --git a/.github/workflows/hol-plugin-scanner.yml b/.github/workflows/hol-plugin-scanner.yml index feb19d1..ce8d1bf 100644 --- a/.github/workflows/hol-plugin-scanner.yml +++ b/.github/workflows/hol-plugin-scanner.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - - name: Validate v0.14 wrapper contract + - name: Validate v0.15 wrapper contract run: sh scripts/validate-plugin.sh - name: HOL Plugin Scanner uses: hashgraph-online/ai-plugin-scanner-action@5d17bb20ed8878ef1e82ed3ddf433522dbd36b26 diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index afc1fbc..69d48e4 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -10,8 +10,8 @@ permissions: contents: read env: - TREE_RING_VERSION: "0.14.0" - TREE_RING_LINUX_X86_64_SHA256: "c72191aca81f195472272a1962df354fe0af04a08b01a7472a1faf987cd177fa" + TREE_RING_VERSION: "0.15.0" + TREE_RING_LINUX_X86_64_SHA256: "9b47873268dbb94712a49b02bd785cc69507facee1e879e46e6922778b4afbe6" jobs: validate: @@ -19,7 +19,7 @@ jobs: steps: - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1 - - name: Install checksum-pinned Tree Ring v0.14 + - name: Install checksum-pinned Tree Ring v0.15 shell: bash run: | set -euo pipefail @@ -58,6 +58,6 @@ jobs: - name: Validate plugin package run: sh scripts/validate-plugin.sh - - name: Smoke Tree Ring v0.14 integration + - name: Smoke Tree Ring v0.15 integration shell: bash - run: bash scripts/smoke_v014.sh + run: bash scripts/smoke_v015.sh diff --git a/README.md b/README.md index f1cd715..76c8e33 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,10 @@ This plugin packages one Codex skill that teaches agents when to recall, write, audit, consolidate, and forget project memory using the open-source [Tree Ring Memory](https://github.com/TerminallyLazy/Tree-Ring-Memory) CLI. -Plugin `0.3.2` requires Tree Ring Memory CLI **>= 0.14.0**. The minimum is -intentional: v0.14 adds receipt-backed harness readiness on top of the v0.13 -schema-v3, coordinated-write, and idempotency contracts used by this guidance. +Plugin `0.3.3` requires Tree Ring Memory CLI **>= 0.15.0**. The minimum adds +verified project-local bootstrap and scope-preserving CLI updates on top of the +receipt-backed harness, schema-v3, coordinated-write, and idempotency contracts +used by this guidance. The public ZIP is a skills-only package. It intentionally omits `interface.screenshots`, which OpenAI's ZIP ingestion does not accept for this @@ -31,18 +32,21 @@ privacy-safe. observed use in a fresh agent session. - Explicit forgetting, redaction, and supersession guidance. - DOX and Revolve adapter usage with dry-run-first guardrails. +- Verified project-local CLI bootstrap and scope-preserving update guidance. ## Install Tree Ring Memory -macOS ARM64 with Homebrew: +From the actual project root, after the user has authorized Tree Ring setup: ```bash -brew tap TerminallyLazy/tree-ring -brew install tree-ring +curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init --release latest --no-animation +.tree-ring/bin/tree-ring --root .tree-ring integrations status --verbose ``` -For other install paths, use the canonical project README: - +The verified prebuilt installer supports macOS ARM64 and Linux x86_64. Homebrew +remains available on macOS with `brew install tree-ring`. The agent may proceed +when the user's request already authorizes setup; otherwise it obtains +permission before the download or software installation. Verify the installed core before using this wrapper: @@ -50,11 +54,15 @@ Verify the installed core before using this wrapper: tree-ring --version ``` -The result must be `tree-ring 0.14.0` or newer. +The result must be `tree-ring 0.15.0` or newer. -If the CLI is absent or older, the plugin reports the limitation. It does not -install or upgrade software, edit shell configuration, or claim a memory action -ran without explicit user permission and observed command output. +Use `tree-ring update --check` for a read-only release check. With update +authorization, `tree-ring update` verifies official assets and preserves the +active project-local, direct-prefix, or Homebrew scope. The plugin does not edit +shell configuration, change global installation scope, or claim a memory action +ran without the required authorization and observed command output. For other +install paths, use the canonical project README: +. ## Use @@ -174,8 +182,8 @@ backup. ## Canonical Project - Framework repo: -- Canonical v0.14 skill: -- v0.14 release: +- Canonical v0.15 skill: +- v0.15 release: - Launch page: - Homebrew tap: diff --git a/SUBMISSION.md b/SUBMISSION.md index 2561aa1..995d271 100644 --- a/SUBMISSION.md +++ b/SUBMISSION.md @@ -17,8 +17,8 @@ Long description: > Tree Ring Memory gives coding agents a lifecycle-aware practice for project > recall, durable decisions, receipt-backed harness readiness, same-host > fan-out/fan-in, idempotent worker writes, coordinator-authorized shared -> publication, explicit forgetting, and privacy-safe memory capture using the -> open-source Tree Ring Memory 0.14 CLI. +> publication, explicit forgetting, verified project setup, scope-preserving +> updates, and privacy-safe memory capture using Tree Ring Memory 0.15. ## Starter Prompts @@ -31,12 +31,12 @@ Long description: 1. Prompt: "Recall what we decided about release behavior in this project." Expected behavior: check the local runtime and project guidance, run scoped recall, and summarize source-linked results. Expected shape: concise memories - with confidence or source context. Fixture: an initialized v0.14 store with a + with confidence or source context. Fixture: an initialized v0.15 store with a project-scoped release decision. 2. Prompt: "Remember that the signed archive must be inspected before release." Expected behavior: confirm the lesson is durable and privacy-safe, then create one concise source-linked memory. Expected shape: the observed CLI result and - stored memory identifier. Fixture: an initialized writable v0.14 store. + stored memory identifier. Fixture: an initialized writable v0.15 store. 3. Prompt: "Audit this store for stale or sensitive memory without changing it." Expected behavior: use report-only audit and maintenance commands. Expected shape: grouped findings and recommended follow-up, with no mutation claim. @@ -49,7 +49,7 @@ Long description: 5. Prompt: "Is Tree Ring active for this Codex project?" Expected behavior: run verbose integration status and report its exact state; configuration alone must not be called active. Expected shape: harness name, - state, capability, and next step. Fixture: a configured v0.14 project without + state, capability, and next step. Fixture: a configured v0.15 project without a fresh matching receipt. 6. Prompt: "Preview the DOX contracts in this repository before syncing them." Expected behavior: read the applicable `AGENTS.md` chain, run DOX sync in @@ -77,15 +77,14 @@ Long description: ## Release Notes -Version 0.3.2 of the v0.14-compatible skills-only package keeps coordinator -capabilities out of shell history by requiring a shell-appropriate no-echo -prompt or approved secret-manager injection, and routes support and security -reports through the canonical repository. It retains the v0.3.1 ZIP-ingestion -fix that removed unsupported `interface.screenshots`, plus runtime preflight, -receipt-backed harness readiness, exact non-active states, same-host -coordination rules, the logo and composer icon, and explicit privacy-safe -fallback when local execution is unavailable. The plugin has no MCP server, -hosted service, credentials, telemetry, or reviewer account requirement. +Version 0.3.3 of the v0.15-compatible skills-only package adds verified +project-local bootstrap, project-root-safe initialization, and scope-preserving +CLI update guidance. It retains the ZIP-ingestion fix that omits unsupported +`interface.screenshots`, plus receipt-backed harness readiness, same-host +coordination rules, safe capability handling, the logo and composer icon, and +guidance-only fallback when local execution is unavailable. The plugin has no +MCP server, hosted service, credentials, telemetry, or reviewer account +requirement. ## Review Note diff --git a/scripts/smoke_v014.sh b/scripts/smoke_v015.sh similarity index 98% rename from scripts/smoke_v014.sh rename to scripts/smoke_v015.sh index 8b711ac..dbfe4a0 100755 --- a/scripts/smoke_v014.sh +++ b/scripts/smoke_v015.sh @@ -7,7 +7,7 @@ if [[ "${tree_ring_bin}" == */* ]]; then else command -v "${tree_ring_bin}" >/dev/null fi -test "$("${tree_ring_bin}" --version)" = "tree-ring 0.14.0" +test "$("${tree_ring_bin}" --version)" = "tree-ring 0.15.0" smoke_base="${RUNNER_TEMP:-${TMPDIR:-/tmp}}" smoke_base="${smoke_base%/}" @@ -255,4 +255,4 @@ snapshot_tree "${store_root}" > "${smoke_dir}/upgraded-before.sha256" snapshot_tree "${store_root}" > "${smoke_dir}/upgraded-after.sha256" cmp "${smoke_dir}/upgraded-before.sha256" "${smoke_dir}/upgraded-after.sha256" -printf 'Tree Ring v0.14 integration smoke passed\n' +printf 'Tree Ring v0.15 integration smoke passed\n' diff --git a/scripts/validate-plugin.sh b/scripts/validate-plugin.sh index 8ccbd51..fbf0756 100755 --- a/scripts/validate-plugin.sh +++ b/scripts/validate-plugin.sh @@ -30,8 +30,8 @@ root = Path(".") manifest = json.loads((root / ".codex-plugin/plugin.json").read_text()) if manifest.get("name") != "tree-ring-memory": raise SystemExit("plugin name must remain tree-ring-memory") -if manifest.get("version") != "0.3.2": - raise SystemExit("wrapper version must be 0.3.2") +if manifest.get("version") != "0.3.3": + raise SystemExit("wrapper version must be 0.3.3") interface = manifest.get("interface", {}) prompts = interface.get("defaultPrompt", []) @@ -66,10 +66,12 @@ if "tree-ring-memory-codex-plugin/issues" in public_text: raise SystemExit("support and security links must use the canonical repository") PY -assert_contains "$README" 'CLI **>= 0.14.0**' +assert_contains "$README" 'CLI **>= 0.15.0**' assert_contains "$README" 'Receipt-Backed Harness Readiness' -assert_contains "$SKILL" 'version: 0.14.0' -assert_contains "$SKILL" 'Runtime Preflight' +assert_contains "$SKILL" 'version: "0.15.0"' +assert_contains "$SKILL" 'Runtime Bootstrap And Updates' +assert_contains "$SKILL" '--project --init --release latest --no-animation' +assert_contains "$SKILL" 'tree-ring update --check' assert_contains "$SKILL" 'DOX Contract Flow' assert_contains "$SKILL" 'tree-ring dox sync --source-root --dry-run' assert_contains "$SKILL" 'Certification Boundary' diff --git a/skills/tree-ring-memory/SKILL.md b/skills/tree-ring-memory/SKILL.md index 0da8d29..f59704d 100644 --- a/skills/tree-ring-memory/SKILL.md +++ b/skills/tree-ring-memory/SKILL.md @@ -1,21 +1,11 @@ --- name: tree-ring-memory description: Guides AI agents in using Tree Ring Memory for durable recall, project decisions, user preferences, warnings, future seeds, privacy-safe memory capture, and lifecycle-aware forgetting. -version: 0.14.0 license: MIT -tags: ["memory", "agents", "recall", "privacy", "projects", "dox", "revolve", "skills", "cli"] -triggers: - - "remember this" - - "recall what we decided" - - "what did we learn" - - "tree ring memory" - - "consolidate memory" - - "forget this" - - "project memory" - - "sync DOX" - - "sync Revolve" - - "evidence loop" - - "multi-agent memory" +metadata: + version: "0.15.0" + tags: "memory, agents, recall, privacy, projects, dox, revolve, skills, cli" + triggers: "remember this; recall what we decided; what did we learn; tree ring memory; consolidate memory; forget this; project memory; sync DOX; sync Revolve; evidence loop; multi-agent memory" --- # Tree Ring Memory @@ -31,23 +21,51 @@ Tree Ring Memory preserves meaningful agent learning like tree rings: - speculative future work stays as seeds - sensitive data is blocked, redacted, or kept out by default -## Runtime Preflight +## Runtime Bootstrap And Updates -Before running a Tree Ring command: +Resolve the actual project root before running Tree Ring. Never initialize a +plugin cache, downloaded package directory, home directory, or arbitrary +working directory by accident. -1. Read project-local `.tree-ring/SKILL.md` and `.tree-ring/CLI.md` when they - exist. They describe the configured root and exact installed commands. -2. Confirm that the local runtime is available: +1. If `/.tree-ring/bin/tree-ring` exists, prefer that binary for + this project. Otherwise check `command -v tree-ring` and run + `tree-ring --version`. +2. Read existing `/.tree-ring/SKILL.md` and `CLI.md` when present. +3. This package targets Tree Ring Memory CLI 0.15.0 or newer. If no compatible + CLI is available and the user's request already authorizes Tree Ring setup, + install the verified current release project-locally from the project root. + Otherwise explain the exact operation and obtain permission before the + network download or software installation: ```bash - tree-ring --version + cd + curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init --release latest --no-animation ``` -3. This package targets Tree Ring Memory CLI 0.14.0 or newer. If the command is - missing or older, do not invent results, edit shell configuration, or install - or upgrade software without the user's explicit permission. Explain the - limitation and point to the canonical install guide: - +4. For an existing global CLI, initialize from the project root with + `tree-ring --root .tree-ring init`. For a project-local CLI, use + `.tree-ring/bin/tree-ring --root .tree-ring init`. This must place + `memory.sqlite`, `AGENTS.md`, `SKILL.md`, and `CLI.md` under that project's + `.tree-ring/` directory. +5. Verify the created paths and run the same binary with + `--root .tree-ring integrations status`. Initialization creates safe local + guidance and bridge material; it is not receipt-backed activation proof. + +Check for releases without changing files with `tree-ring update --check`. Run +`tree-ring update` only when the user has authorized an update. It updates the +active binary in its existing project-local, direct, or Homebrew-managed scope, +verifies official release assets, and must not create a second shadowing binary. +After an update, return to each project root and rerun `tree-ring --root +.tree-ring init` (or the project-local equivalent) to backfill managed guidance +without replacing custom files. + +CLIs older than 0.15.0 do not have `tree-ring update`. Upgrade those with the +same manager or prefix that installed them: `brew upgrade tree-ring` for +Homebrew, `--project --release latest` for an existing project-local install, +or `--install-dir --release latest` for another direct +install. Check `command -v tree-ring` and `which -a tree-ring` afterward. Do not +edit a shell profile or change global installation scope without separate user +authorization. If the current host cannot execute a local shell or access project files, use this skill only as memory-lifecycle guidance. Do not claim that recall, capture, From 3239dc4c8cc5a089c1563c0338b216e82c321734 Mon Sep 17 00:00:00 2001 From: TerminallyLazy Date: Tue, 25 Aug 2026 17:37:17 -0400 Subject: [PATCH 2/2] Harden CLI bootstrap instructions --- README.md | 13 ++++++++++--- scripts/validate-plugin.sh | 2 +- skills/tree-ring-memory/SKILL.md | 14 +++++++++++--- 3 files changed, 22 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 76c8e33..ed6191c 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,18 @@ privacy-safe. From the actual project root, after the user has authorized Tree Ring setup: +Download the official version-pinned `v0.15.0/install.sh` to a temporary file, +verify its SHA-256 is +`ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade`, inspect +it, then run these commands from the project root: + ```bash -curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init --release latest --no-animation +sh --project --init --release latest --no-animation .tree-ring/bin/tree-ring --root .tree-ring integrations status --verbose ``` +Do not pipe a network response directly to a shell. + The verified prebuilt installer supports macOS ARM64 and Linux x86_64. Homebrew remains available on macOS with `brew install tree-ring`. The agent may proceed when the user's request already authorizes setup; otherwise it obtains @@ -182,8 +189,8 @@ backup. ## Canonical Project - Framework repo: -- Canonical v0.15 skill: -- v0.15 release: +- Canonical v0.15 skill: +- v0.15 release: - Launch page: - Homebrew tap: diff --git a/scripts/validate-plugin.sh b/scripts/validate-plugin.sh index fbf0756..93eb239 100755 --- a/scripts/validate-plugin.sh +++ b/scripts/validate-plugin.sh @@ -68,7 +68,7 @@ PY assert_contains "$README" 'CLI **>= 0.15.0**' assert_contains "$README" 'Receipt-Backed Harness Readiness' -assert_contains "$SKILL" 'version: "0.15.0"' +assert_contains "$SKILL" 'version: "0.15.1"' assert_contains "$SKILL" 'Runtime Bootstrap And Updates' assert_contains "$SKILL" '--project --init --release latest --no-animation' assert_contains "$SKILL" 'tree-ring update --check' diff --git a/skills/tree-ring-memory/SKILL.md b/skills/tree-ring-memory/SKILL.md index f59704d..9a82aa4 100644 --- a/skills/tree-ring-memory/SKILL.md +++ b/skills/tree-ring-memory/SKILL.md @@ -3,7 +3,7 @@ name: tree-ring-memory description: Guides AI agents in using Tree Ring Memory for durable recall, project decisions, user preferences, warnings, future seeds, privacy-safe memory capture, and lifecycle-aware forgetting. license: MIT metadata: - version: "0.15.0" + version: "0.15.1" tags: "memory, agents, recall, privacy, projects, dox, revolve, skills, cli" triggers: "remember this; recall what we decided; what did we learn; tree ring memory; consolidate memory; forget this; project memory; sync DOX; sync Revolve; evidence loop; multi-agent memory" --- @@ -35,13 +35,21 @@ working directory by accident. CLI is available and the user's request already authorizes Tree Ring setup, install the verified current release project-locally from the project root. Otherwise explain the exact operation and obtain permission before the - network download or software installation: + network download or software installation. Download the official, + version-pinned `v0.15.0/install.sh` installer to a temporary file, verify its + SHA-256 is + `ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade`, + inspect it, and only then run: ```bash cd - curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init --release latest --no-animation + sh --project --init --release latest --no-animation ``` + Do not pipe a network response directly to a shell. The installer verifies + the selected release archive against its published SHA-256 before placing + the binary at `/.tree-ring/bin/tree-ring`. + 4. For an existing global CLI, initialize from the project root with `tree-ring --root .tree-ring init`. For a project-local CLI, use `.tree-ring/bin/tree-ring --root .tree-ring init`. This must place