echo/MAINTENANCE.md

echo-memory — Maintenance & repo hygiene (M5)

Low-lift cleanups that remove "which copy is canonical?" traps before tagging 1.0. None of these change runtime behavior; they reduce drift and confusion.

Canonical source tree

• echo-memory.plugin.src/ is the single canonical source tree. ✅
• codex plugin/ has already drifted — it lacks the 0.9 modules (echo_index.py, echo_links.py, echo_ops.py, sweep.py, check_routing.py).
  • Decide: regenerate it from the canonical tree as a build target, or delete it and document the codex/CoWork packaging step instead.
  • Until resolved, add a codex plugin/README.md note: "derived — do not edit by hand."

Build artifacts

The repo root carries every historical build (echo-memory-0.6.0.plugin … echo-memory-0.9.0.plugin) plus echo-memory.plugin.

• Keep only the latest echo-memory.plugin (the installable) tracked; move versioned zips to GitHub Releases (or a dist/ that is git-ignored).
• Add *.plugin build outputs to .gitignore except the current pointer, if desired.
• .gitignore added (.DS_Store, __pycache__, local .echo-memory/, eval output).

plugin.json completeness

• Add license (UNLICENSED — personal, not for distribution).
• Version bumped to 1.0.0.
• Add homepage / repository URL (optional — repo URL not yet decided).
• (Optional) register slash commands in the manifest; they're auto-discovered from commands/ today (echo-load|save|recall|triage|health|sweep|reflect|doctor).

Docs freshness

• eval/run_eval.py still benchmarks 0.6 vs 0.7 — refresh to current (open H4 follow-up).
• README version-history has a 1.0.0 entry; title bumped to v1.0.0.
• Scrub the literal bearer token from docs → $ECHO_KEY placeholder (M1, done: api-reference.md ×11, SKILL.md, bootstrap.md, eval harness). Superseded in 1.3/1.4: key resolution now lives in echo_config.py (machine-local ~/.claude/echo-memory/config.json, ECHO_* env overrides, and empty-in-source DEFAULT_* constants filled only by build.py --bake-key for per-user artifacts in gitignored dist/). API-KEY-SETUP.md and the old ~/.echo-memory/credentials fallback are gone; the committed tree ships zero credentials.

Building the .plugin artifact

python build.py zips echo-memory.plugin.src/ into echo-memory-<version>.plugin (version read from the manifest) and refreshes the echo-memory.plugin pointer. Deterministic (sorted entries + fixed timestamp → byte-identical rebuilds). Flags:

• --strip-key — force-blank the echo_config.py DEFAULT_* constants for a guaranteed token-free artifact (a clean source build is already token-free; this is the belt-and-braces flag).
• --bake-key --from <config.json> [--label <name>] — per-user secret-bearing artifact in gitignored dist/; deliver directly to that one user, never commit (see README).
• --no-pointer — skip refreshing echo-memory.plugin.
• --outdir DIR — write artifacts elsewhere.

Without --strip-key the build warns that the baked-in token is present.

Pre-1.0 release checklist

• All 10 roadmap items wired; scaffold TODOs cleared (see ROADMAP-1.0.md status table).
• schema_version bumped to 4 (sweep/migrate); migrate.py [3→4] step added. Verify on a copy of the live vault before migrating it (it currently reports schema 3).
• Offline suites green in CI on Win/macOS/Linux × Py 3.10/3.12 (check_routing, test_echo_client, test_v1_scaffold, test_features, test_patch_semantics, test_offline_queue, test_reflect).
• No live secret in the tracked tree or the built .plugin — one line left: delete echo.py DEFAULT_KEY after ECHO_KEY/credentials are set everywhere (per API-KEY-SETUP.md).
• eval/run_eval.py reports current-version retrieval/durability metrics (open follow-up).