jason/chorus
1
0
Fork 0
forked from jason/echo
Code Pull Requests Activity

Phase 5: group-voice docs, onboarding runbook, CHORUS icon — v2.0.0-rc.1

Browse Source 
The final phase of CHORUS-PLAN.md. Code- and doc-complete for group use;
rc pends live deployment at chorusapi.mpm.to.

- Repo README rewritten for CHORUS: group model (schema 5), concurrency
  posture, configuration, baked-build onboarding, layout, testing, 2.0
  version history (ECHO history referenced at the fork tag).
- Operator→member voice sweep across SKILL.md (incl. the trigger
  description, now group-aware), all references, 8 command docs, plugin
  README; member preferences / semantic layer / triage guidance describe
  the group model.
- docs/ONBOARDING.md: member runbook — vault stand-up, per-member config,
  bake, deliver, self-onboarding first load, norms, offboarding.
- docs/USAGE.md rewritten as the member usage guide.
- New icon: chorus-icon.svg + 1024/512/64 PNGs (three voices, one center).
- Removed ECHO-era assets (icons, spec PDF, perf briefs); ECHO planning
  docs retired to docs/history/. All preserved at echo-fork-point.
- eval/README documents test_multimember.py. Manifest -> 2.0.0-rc.1;
  rebuilt chorus-memory.plugin.

Verified: routing-sync, 25/25 unit, scaffold, 5 mock e2e suites,
run_eval metrics green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jason Stedwell
2026-07-21 15:41:58 -05:00
parent 1a7690426f
commit f2bfd70dd4
36 changed files with 324 additions and 807 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/history/ECHO-ROADMAP-2.0.md
+95
View File
@@ -0,0 +1,95 @@
# echo-memory — Roadmap to v2.0.0
> Status: **draft.** Current shipping version: **1.5.1**. Interim work tracked in
> `TODO-1.6.md`.
>
> **2.0 thesis: a packaging & structure major.** Nothing here changes what the plugin
> *does* for memory — 2.0 is the release where the repo layout, artifact policy, and
> plugin format are cleaned up in ways that are breaking for how the plugin is
> *distributed and installed*, so the major version signals "reinstall everything,
> re-clone expectations." Feature work keeps landing in 1.6.x until this is ready.
>
> This roadmap absorbs every open item from the retired `MAINTENANCE.md` (M5)
> checklist; the mapping is noted per item.
---
## 1. Repo-root artifact policy (from MAINTENANCE › Build artifacts)
The repo root tracks every historical build (`echo-memory-0.6.0.plugin` …
`echo-memory-1.5.1.plugin`) plus the `echo-memory.plugin` pointer. 2.0 changes the
policy — **breaking for anyone who pulls artifacts straight from the repo**:
- [ ] Track only `echo-memory.plugin` (the current installable); delete the versioned
zips from the tree.
- [ ] Publish versioned builds as **Gitea releases** on `git.alwisp.com/jason/echo`
instead (one release per tag, artifact attached).
- [ ] `.gitignore`: `*.plugin` except the pointer.
- [ ] Tag releases going forward (`v2.0.0`, …) so the release page is the version
history for artifacts, and the README table stays the narrative history.
## 2. Complete the skills-format migration (finishes the 1.6 work)
1.6 migrates the eight slash commands to `skills/*/SKILL.md` with both formats
coexisting (see `TODO-1.6.md`). 2.0 finishes it:
- [ ] **Delete the legacy `commands/` directory** — the packaging break that partly
motivates the major bump.
- [ ] Re-verify desktop + CoWork installs of the skills-only artifact.
- [ ] Update SKILL.md / README / command docs that reference `commands/`.
## 3. Codex packaging (from MAINTENANCE › Canonical source tree)
The drifted `codex plugin/` tree was **deleted on 2026-07-03** (operator decision:
Codex usage doesn't currently justify a maintained second build; it will be
regenerated after 2.0 if needed). What remains for 2.0:
- [ ] If Codex support returns: implement it as a **build target** generated from the
canonical `echo-memory.plugin.src/` tree (`build.py --target codex` or similar) —
never as a second hand-maintained source tree (that's how the drift happened).
- [ ] Otherwise: a short "packaging for other agent runtimes" note in the README
documenting what a Codex/other-runtime port needs (manifest shape, skill entry
point, script invocation).
## 4. Eval refresh — publish current-version metrics (from MAINTENANCE › Docs freshness; ROADMAP-1.0 H4 leftover) — ✅ DONE
`run_eval.py` was rewritten from the stale 0.6-vs-0.7 A/B into the current-version
metrics harness (retrieval / dedup / write-safety / durability); numbers published in
the README. Re-run it per release and refresh the README table.
- [x] Refresh `run_eval.py` to measure the current version — **done 2026-07-03**:
retrieval P@5/R@5/MRR + session/journal answerability + freshness top-1 (vs a
keyword/entities-only baseline), duplicate rate gate-on/off, silent-write-failure
rate under fault injection, offline-queue durability. `results/latest.json`.
- [x] Publish the numbers in the README and mark the old A/B harness historical
(git history) — **done 2026-07-03**.
## 5. Repo hygiene odds & ends
- [x] Retire `ROADMAP-1.0.md` (fully shipped; in git history) — **done 2026-07-03**.
- [ ] Root README "Repository layout" section updated for the post-2.0 tree
(no versioned zips, no codex tree, skills-only plugin).
- [x] `echo-improvements-prompt.md` (the 1.5.0 field report) moved to `docs/history/`
— **done 2026-07-03**.
---
## MAINTENANCE.md disposition (why it was removed)
Every item from the retired checklist is either **done** or **absorbed above**:
| MAINTENANCE item | Status |
|---|---|
| Canonical tree = `echo-memory.plugin.src/` | Done (0.x) |
| `codex plugin/` decide regenerate-or-delete | **Deleted 2026-07-03**; regenerate-as-build-target tracked in §3 |
| Prune historical `.plugin` zips; gitignore policy | §1 |
| `.gitignore` basics | Done (1.0) |
| plugin.json `license` + version | Done (1.0) |
| plugin.json `homepage` | `TODO-1.6.md` §2 (URL now decided) |
| Register commands in manifest | Superseded by the skills migration (`TODO-1.6.md` §1, finished in §2 here) |
| `run_eval.py` refresh to current metrics | §4 |
| Secret handling (M1) | Done — superseded by `echo_config` in 1.3/1.4; committed tree ships zero credentials |
| Pre-1.0 checklist | Done/obsolete (1.0 shipped; the `DEFAULT_KEY` line it referenced was removed in 1.3) |
Build flags (`--bake-key`, `--strip-key`, `--no-pointer`, `--outdir`) are documented
in `build.py`'s docstring and the README Configuration section.
docs/history/ECHO-TODO-1.6.md
+63
View File
@@ -0,0 +1,63 @@
# echo-memory — v1.6 TODO
> Working list for the next minor release. Started 2026-07-03, right after 1.5.1
> shipped. **Add findings from 1.5.x live testing to the "Surfaced in testing"
> section as they come up** — that's what this doc is for.
## 1. Migrate the eight slash commands to the skills format
The installer flags the plugin's `commands/` directory as the legacy format
("Both formats work — consider migrating to skills/*/SKILL.md"). Confirmed against
the official docs (code.claude.com/docs/en/skills.md, plugins.md):
- **Non-breaking.** `commands/echo-save.md` → `skills/echo-save/SKILL.md` keeps the
invocation name: `/echo-save` works identically. No deprecation date on `commands/`;
this is future-proofing, not a fire.
- **Do it for the features, not the notice:**
- [ ] `allowed-tools` per skill — pre-authorize the resolved `python3 "$ECHO" …`
invocations so `/echo-load`, `/echo-health`, `/echo-recall` stop prompting
(1.4.2 hand-broadened two commands; the skill format does this properly).
- [ ] `disable-model-invocation: true` on the write-heavy entry points
(`/echo-sweep`, `/echo-triage`) so only the operator triggers them; leave the
read-side ones model-invocable.
- [ ] De-duplicate the CoWork `$ECHO` path-resolution block currently copy-pasted
into all eight command bodies — each skill folder can carry a shared snippet.
- [ ] `argument-hint` carries over as-is; `$ARGUMENTS` substitution unchanged.
- [ ] Verify a migrated build installs cleanly on desktop **and** in a CoWork session
before deleting `commands/` (deleting the legacy dir is a 2.0 item —
see `ROADMAP-2.0.md`; in 1.6 both may coexist).
## 2. plugin.json completeness (from the old MAINTENANCE checklist)
- [ ] Add `homepage` / repository URL — now decided: `https://git.alwisp.com/jason/echo`.
## 3. Vault follow-ups (noticed during the 1.5.0 dead-link cleanup)
Three of the 27 unwrapped "dead" links were actually **typos pointing at real notes**;
they were unwrapped per instruction but repointing them would restore real graph edges:
- [ ] `projects/active/forgerunner.md` + `_agent/sessions/2026-06-29-2200-forgerunner-v010-ship.md`:
"Gitea CI Docker jobs run on the host label" → the decision
`decisions/by-date/2026-06-29-gitea-ci-docker-jobs-run-on-the-host-lab.md` ("lab", not "label").
- [ ] `projects/active/mpm-brand-voice.md`: "Message Point Media (MPM)" ×3 → the company
note `resources/companies/mpm.md` (or whatever is canonical for MPM).
## 4. Surfaced in 1.5.x testing
*(add items here as the new plugin gets real use)*
- [ ] **Lint blind spot: retired dirs masked by the leaf-README route** (found 2026-07-03).
`archive/` and `_agent/outputs/` are retired/unrouted pre-0.6 leftovers that survived
in the live vault holding only their seed READMEs — and the permissive `leaf-readme`
route (`^(.+/)?README\.md$`) matches first, so `vault_lint` never flagged them.
Fix: in the path-membership check, test the *directory* against retired/unknown
patterns even when the only file in it is a README (e.g. evaluate `dirname(path) + "/"`
against retired patterns before letting `leaf-readme` absolve the file), or drop the
seed-README exemption inside retired trees. Add a lint test seeding
`archive/notes/README.md` → must flag `retired-path`.
*Related learning (same cleanup, 2026-07-03):* the REST API **cannot delete
directories** — removing a folder's last file orphans the empty folder on disk
(the REST listing 404s, falsely reading as gone; Obsidian still shows it — manual
deletion required). Documented in `references/api-reference.md` › Deleting Files
and in the vault's `resources/references/obsidian-local-rest-api.md`. Any future
"remove retired tree" guidance must include the manual folder-cleanup step.