From 1a5b8a651399bdc4983770af01046fb2658eb8ef Mon Sep 17 00:00:00 2001 From: Willi Budzinski Date: Fri, 19 Jun 2026 15:25:28 +0200 Subject: [PATCH 1/2] fix: document zed fallback and stabilize backup test --- README.md | 4 +- .../todo.md | 46 +++++++++ .../plan.md | 97 +++++++++++++++++++ .../todo.md | 95 ++++++++++++++++++ test/backup-scheduler.test.ts | 16 ++- 5 files changed, 254 insertions(+), 4 deletions(-) create mode 100644 docs/todos/2026-06-19-backup-scheduler-test-race/todo.md create mode 100644 docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/plan.md create mode 100644 docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md diff --git a/README.md b/README.md index b31fc83b0..8a7e48f34 100644 --- a/README.md +++ b/README.md @@ -662,7 +662,7 @@ This is **complementary** to `agentmemory connect `: - `agentmemory connect ` writes the MCP server config so the tools are available. - `npx skills add rohitg00/agentmemory` installs the skills so the agent knows when to call them. -For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 15 SKILL.md files under the agent's native skill directory yourself — same format works everywhere. +For current Zed, skills can also be installed manually under `~/.agents/skills/` for global use or `/.agents/skills/` for project-local use. Older Zed v1.3.x and below builds did not have this Skills surface; for those versions, drop the 15 SKILL.md files under the agent's native skill directory yourself. #### Standard MCP block @@ -723,7 +723,7 @@ For central memory deployments where an empty local fallback would be misleading | **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` writes the user-level config. Workspace overrides go in `.kiro/settings/mcp.json` next to your code. | | **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` writes the standard `mcpServers` block. Warp also auto-discovers skills from `.claude/skills/` — once the Claude Code plugin is installed the 8 agentmemory skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) appear natively in Warp's slash-command palette. | | **Continue.dev** | `~/.continue/config.yaml` (preferred) or `config.json` (legacy) | `agentmemory connect continue` creates `config.yaml` from scratch when neither exists, or modifies existing `config.json`. **If you already have `config.yaml`** the adapter prints the exact block to paste under `mcpServers:` — it won't silently rewrite your yaml because preserving comments and anchors safely needs a YAML parser the package doesn't ship. Continue uses array form (not object) for `mcpServers`. | -| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` writes under `context_servers` (Zed's key, NOT `mcpServers`). Remote MCP servers can be wired via `{"url": "..."}` instead. | +| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` writes under `context_servers` (Zed's key, NOT `mcpServers`). Remote MCP servers can be wired via `{"url": "..."}` instead. Zed Agent also auto-loads project instructions from root compatibility files such as `.clinerules` and `AGENTS.md`, so Cline-compatible or cross-agent project guidance applies without separate Zed adapter code when those files are present. | | **Droid (Factory.ai, MCP only)** | `~/.factory/mcp.json` | `agentmemory connect droid` writes the standard `mcpServers` block. Project-scoped overrides go in `/.factory/mcp.json`. The `/mcp` slash command inside droid lists configured servers. | | **Goose** | Goose MCP settings UI | Same `mcpServers` block — use `goose configure` → Add Extension → MCP. Direct YAML edit at `~/.config/goose/config.yaml` is supported but the schema uses `extensions:` + `cmd` (not `mcpServers:` + `command`). | | **Aider** | n/a | Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. | diff --git a/docs/todos/2026-06-19-backup-scheduler-test-race/todo.md b/docs/todos/2026-06-19-backup-scheduler-test-race/todo.md new file mode 100644 index 000000000..855814ee2 --- /dev/null +++ b/docs/todos/2026-06-19-backup-scheduler-test-race/todo.md @@ -0,0 +1,46 @@ +# Backup Scheduler Test Race + +## Scope + +- Repository: `/Users/A1538552/.codex/worktrees/c9ff/agentmemory` +- Branch: `issue/278-zed-cline-agents-fallback` +- Trigger: Human Checkpoint after issue #278 verification was blocked by repeated full-suite failures in `test/backup-scheduler.test.ts`. + +## Sprint Contract + +- Goal: make the backup scheduler schedule test wait for the scheduled backup write to complete before test cleanup. +- Scope: `test/backup-scheduler.test.ts` and task records only. +- Non-goals: no production scheduler API changes, no backup behavior changes, no timer interval policy changes. +- Acceptance criteria: + - The schedule test drives the interval deterministically. + - The test asserts that the backup export file exists before cleanup can remove the temp directory. + - `corepack pnpm exec vitest run test/backup-scheduler.test.ts` passes. + - `corepack pnpm test` passes. +- Intended verification: + - Existing full-suite failures are the RED evidence. + - Targeted backup scheduler test. + - Full repo test gate. + - Staged Gitleaks before commit. +- Stop conditions: production API change required, repeated full-suite failures after the deterministic test fix, or unrelated failures needing separate triage. + +## Failure Evidence + +- `corepack pnpm test` failed twice after the issue #278 docs were staged. +- Both failures were `ENOTEMPTY, Directory not empty` in `test/backup-scheduler.test.ts:35` while removing `/tmp/agentmemory-backup-test-*`. +- Targeted `corepack pnpm exec vitest run test/backup-scheduler.test.ts` passed once, indicating a full-suite scheduling race. +- Root cause hypothesis: the schedule test waits only for `sdk.trigger` to be called, while `startBackupScheduler()` starts `runBackupOnce()` as an unawaited interval callback. Cleanup can race the backup file write. + +## Progress + +- [x] Failure evidence gathered. +- [x] Test made deterministic. +- [x] Targeted verification run. +- [x] Full verification run. +- [x] Final notes recorded. + +## Review Notes + +- First fix attempt used fake timers but waited before clearing the interval. `vi.waitFor` advanced fake timers repeatedly and produced many backup files, so the targeted scheduler test failed. Changed approach: advance exactly one interval tick, clear the interval immediately, then wait for that tick's export and file write side effects. +- Targeted verification: `corepack pnpm exec vitest run test/backup-scheduler.test.ts` exited 0; 1 test file passed, 8 tests passed. +- Full verification: `corepack pnpm test` exited 0; 206 test files passed, 2,825 tests passed. +- Sprint Contract status: met. The schedule test now uses fake timers to advance one interval tick, clears the interval before `vi.waitFor` can advance timers again, and waits until the backup file appears before cleanup. diff --git a/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/plan.md b/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/plan.md new file mode 100644 index 000000000..2925b1cc7 --- /dev/null +++ b/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/plan.md @@ -0,0 +1,97 @@ +# Zed Cline AGENTS Fallback Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Document issue #278's Zed Agent instruction fallback without changing adapter behavior. + +**Architecture:** This is a README-only documentation fix. Existing connect adapters stay MCP-only: Cline writes `mcpServers`, Zed writes `context_servers`, and Zed Agent independently loads project instruction files such as `.clinerules` and `AGENTS.md`. + +**Tech Stack:** Markdown documentation, ripgrep verification, git diff review. + +--- + +### Task 1: Update README Zed Guidance + +**Files:** +- Modify: `README.md:650-726` +- Modify: `docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md` + +- [x] **Step 1: Verify the documentation gap** + +Run: + +```bash +rg -n "Zed Agent auto-loads project instructions|\\.agents/skills|Project instructions.*AGENTS\\.md" README.md +``` + +Expected: exit 1 with no matches, proving README does not yet document the Zed instruction fallback or current Zed skill directories. + +- [x] **Step 2: Add current Zed skill-directory note** + +Replace the existing single-sentence Zed skills caveat near `README.md:665` with this content: + +```markdown +For current Zed, skills can also be installed manually under `~/.agents/skills/` for global use or `/.agents/skills/` for project-local use. Older Zed v1.3.x and below builds did not have this Skills surface; for those versions, drop the 15 SKILL.md files under the agent's native skill directory yourself. +``` + +- [x] **Step 3: Add Zed instruction fallback wording** + +Update the Zed row in the Other Agents table to keep the MCP setup and add this instruction fallback: + +```markdown +| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` writes under `context_servers` (Zed's key, NOT `mcpServers`). Remote MCP servers can be wired via `{"url": "..."}` instead. Zed Agent also auto-loads project instructions from root compatibility files such as `.clinerules` and `AGENTS.md`, so Cline-compatible or cross-agent project guidance applies without separate Zed adapter code when those files are present. | +``` + +- [x] **Step 4: Verify README wording** + +Run: + +```bash +rg -n "Zed Agent auto-loads project instructions|\\.agents/skills|context_servers|\\.clinerules|AGENTS\\.md" README.md +``` + +Expected: matches the new Zed skill and instruction fallback guidance plus the existing `context_servers` wording. + +- [x] **Step 5: Run whitespace diff check** + +Run: + +```bash +git diff --check +``` + +Expected: exit 0. + +- [x] **Step 6: Review final diff** + +Run: + +```bash +git status -sb --untracked-files=all +sed -n '1,240p' docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md +sed -n '1,240p' docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/plan.md +git diff -- README.md +``` + +Expected for the issue #278 documentation change: task records and README documentation changed; no production source, generated files, adapter code, or instruction files changed. After the Human Checkpoint to fix the verification blocker, the final branch also includes the scoped scheduler test race fix recorded in `docs/todos/2026-06-19-backup-scheduler-test-race/todo.md`. + +- [x] **Step 7: Run full repo test gate** + +Run: + +```bash +corepack pnpm test +``` + +Expected: exit 0. + +- [x] **Step 8: Resolve approved verification blocker** + +After the Human Checkpoint, make `test/backup-scheduler.test.ts` deterministic by driving one fake-timer interval tick, clearing the interval immediately, and waiting for the backup file before cleanup. Verify with: + +```bash +corepack pnpm exec vitest run test/backup-scheduler.test.ts +corepack pnpm test +``` + +Expected: both commands exit 0. diff --git a/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md b/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md new file mode 100644 index 000000000..b907d46f9 --- /dev/null +++ b/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md @@ -0,0 +1,95 @@ +# Issue 278 - Zed Cline AGENTS fallback + +## Scope + +- Repository: `/Users/A1538552/.codex/worktrees/c9ff/agentmemory` +- Branch: `issue/278-zed-cline-agents-fallback` +- Issue: `https://github.com/wbugitlab1/agentmemory/issues/278` +- Parent batch record: `docs/todos/2026-06-19-issue-triage-batch-148-287/todo.md` in the parent checkout; not edited from this worktree. + +## Sprint Contract + +- Goal: document how current Zed Agent picks up agentmemory guidance through cross-agent instruction files while keeping MCP setup under `context_servers`. +- Scope: README documentation for Zed instruction fallback and current Zed skill layout. +- Non-goals: no Zed adapter behavior changes, no Cline adapter behavior changes, no generated instruction or rules files, no dependency or schema changes. +- Acceptance criteria: + - README states that `agentmemory connect zed` remains MCP-only and writes `context_servers`. + - README states that Zed Agent auto-loads project instructions from root compatibility files including `.clinerules` and `AGENTS.md`. + - README states current Zed skills can be installed under `~/.agents/skills/` or `/.agents/skills/`. + - README avoids claiming `agentmemory connect cline` installs Cline rules. +- Intended verification: + - RED documentation search before edit. + - Focused README searches after edit. + - `git diff --check`. + - `corepack pnpm test`. + - Semgrep for the agent-workflow documentation surface. + - Full diff review. + - Before commit: staged gitleaks per repo policy. +- Known boundaries: agent workflow and instruction surfaces are sensitive; this task documents existing Zed behavior only and does not create or mutate instruction files. +- Stop conditions: conflicting arena validity conclusions, request to add generated instruction files or adapter behavior, skipped/failing verification requiring acceptance. + +## Arena Synthesis + +- Candidate 1: valid docs gap; strongest note was duplicate/staleness handling and warning not to document `.clinerules/agentmemory.md` as Zed-loaded without proof. +- Candidate 2: valid docs gap; strongest note was safer wording around "current Zed" instead of over-specific release claims. +- Candidate 3: valid docs gap; selected as base by cross-judge because it cleanly scoped the claim to Zed Agent, not every external agent launched inside Zed. +- Cross-judge verdict: issue #278 is valid as a README documentation gap, not an adapter bug. No candidates recommended code changes. +- Graft decision: use Candidate 3's base, Candidate 1's duplicate/staleness and instruction-surface caution, and Candidate 2's release-wording caution. + +## Feature / Verification Matrix + +| Change | Verification method | Status | Evidence | +|---|---|---|---| +| Document Zed Agent project instruction auto-load via `.clinerules` and `AGENTS.md` | `rg -n "Zed Agent auto-loads project instructions|\\.agents/skills|context_servers|\\.clinerules|AGENTS\\.md" README.md` | done | README line 726 contains Zed Agent auto-load guidance and preserves `context_servers` wording | +| Document current Zed skill directories | `rg -n "\\.agents/skills" README.md` | done | README line 665 documents `~/.agents/skills/` and `/.agents/skills/` | +| Preserve MCP-only adapter behavior | Diff review confirms no connect adapter, generated instruction file, or production source change | done | Final diff changes README, task records, and `test/backup-scheduler.test.ts` only; no Cline/Zed adapter code changed | + +## Subagent Ledger + +| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk | +|---|---|---:|---|---|---| +| Arena candidate 1 | Read-only issue validity and fix direction | No | Report | Valid docs gap; README-only | None material | +| Arena candidate 2 | Read-only issue validity and fix direction | No | Report | Valid docs gap; README-only | Release wording caution | +| Arena candidate 3 | Read-only issue validity and fix direction | No | Report | Valid docs gap; README-only | Scope wording caution | +| Arena judge | Read-only candidate scoring | No | Synthesis | Candidate 3 base, docs-only fix | None material | + +## Progress + +- [x] Root instructions inspected. +- [x] Git state inspected: clean branch from `origin/main`. +- [x] Issue evidence inspected: issue #278 open, no comments. +- [x] Arena completed and synthesized. +- [x] RED documentation search run before edit; target README wording absent. +- [x] README updated. +- [x] Focused README search and `git diff --check` run. +- [x] `corepack pnpm test` green after final staged state. +- [x] Final review subagents completed. +- [x] Semgrep run. +- [x] Final staged Gitleaks run. +- [x] Final review notes recorded. + +## Review Notes + +- Focused README search after edit found expected matches at README lines 665 and 726. +- `git diff --check` exited 0. +- Dependency setup for verification used `corepack pnpm install --frozen-lockfile --ignore-scripts` from a sanitized environment because `node_modules` was absent. It exited 0 and did not change package metadata. +- `corepack pnpm test` initially exited 0 before final record cleanup: 206 test files passed, 2,825 tests passed. +- Final `corepack pnpm test` after the approved scheduler test fix exited 0: 206 test files passed, 2,825 tests passed. +- Final security/scope review: ACCEPT; no auth, secrets, production source, generated files, instruction files, or adapter behavior changes found. The only non-doc code change is the scoped scheduler test race fix. +- Final maintainability/docs review: ACCEPT; README wording keeps Zed MCP setup under `context_servers`, describes Zed Agent instruction fallback, and does not claim `agentmemory connect cline` installs rules. +- Final verification review found two Medium process gaps: the task record omitted the repo-required full test gate, and the plan's final diff command did not include untracked task record contents. Both were valid and fixed in this record/plan update. +- Final `semgrep scan --config p/default --error --metrics=off .` exited 0: 0 findings, 920 tracked files scanned, 545 rules run. +- Final staged `gitleaks protect --staged --redact` exited 0 with no leaks found. +- Sprint Contract status: all acceptance criteria met. README documents Zed MCP under `context_servers`, Zed Agent project instruction fallback via `.clinerules` and `AGENTS.md`, current Zed skill directories, and avoids claiming the Cline MCP adapter installs rules. +- Residual risk: Zed documentation is current as of 2026-06-19 and may evolve; this change uses "current Zed" wording and does not add behavior. + +## Verification Blocker + +- After final staged state, `corepack pnpm test` failed twice with the same unrelated cleanup race in `test/backup-scheduler.test.ts`: + - First failure: 205 test files passed, 1 failed; 2,824 tests passed, 1 failed. Error: `ENOTEMPTY, Directory not empty: /tmp/agentmemory-backup-test-iokc8B` at `test/backup-scheduler.test.ts:35`. + - Targeted rerun `corepack pnpm exec vitest run test/backup-scheduler.test.ts` exited 0: 8 tests passed. + - Second full-suite failure: 205 test files passed, 1 failed; 2,824 tests passed, 1 failed. Error: `ENOTEMPTY, Directory not empty: /tmp/agentmemory-backup-test-aXatR2` at `test/backup-scheduler.test.ts:35`. +- Suspected failure mode: `startBackupScheduler()` clears the interval handle in the test, but the interval callback starts `runBackupOnce()` with `void` and does not await in-flight backup writes; under full-suite scheduling, a backup JSON can appear after `afterEach` starts removing the temp directory. +- Changed next approach: stopped before a third full-suite retry. Fixing the scheduler/test race would be outside issue #278's README-only scope and needs a Human Checkpoint before expanding this branch. +- Human Checkpoint: user replied "fix it" after the blocker was reported. The backup scheduler race fix is tracked separately in `docs/todos/2026-06-19-backup-scheduler-test-race/todo.md`. +- Resolution: `test/backup-scheduler.test.ts` now drives one fake-timer interval tick, clears the interval immediately, and waits for the backup file before cleanup. Targeted scheduler verification exited 0 with 8 tests passed; final `corepack pnpm test` exited 0 with 206 test files and 2,825 tests passed. diff --git a/test/backup-scheduler.test.ts b/test/backup-scheduler.test.ts index 0f9cb939a..1232c7fcd 100644 --- a/test/backup-scheduler.test.ts +++ b/test/backup-scheduler.test.ts @@ -213,8 +213,9 @@ describe("backup scheduler", () => { it("runs backups on the configured schedule", async () => { const dir = makeTempDir(); const sdk = { trigger: vi.fn(async () => exportData()) }; + vi.useFakeTimers(); - const handle = startBackupScheduler( + let handle = startBackupScheduler( sdk as never, {}, { @@ -227,14 +228,25 @@ describe("backup scheduler", () => { expect(handle).not.toBeNull(); try { + await vi.advanceTimersByTimeAsync(10); + clearInterval(handle!); + handle = null; await vi.waitFor(() => expect(sdk.trigger).toHaveBeenCalledWith({ function_id: "mem::export", payload: {}, }), ); + await vi.waitFor(() => { + const files = readdirSync(dir).filter((name) => + name.startsWith("agentmemory-backup-"), + ); + expect(files).toEqual([ + expect.stringMatching(/^agentmemory-backup-/), + ]); + }); } finally { - clearInterval(handle!); + if (handle) clearInterval(handle); } }); }); From ececf88e86b184eac9bae528d2e4c1e2b1ea0a8f Mon Sep 17 00:00:00 2001 From: Willi Budzinski Date: Fri, 19 Jun 2026 15:29:51 +0200 Subject: [PATCH 2/2] docs: record issue 278 post-merge verification --- .../2026-06-19-issue-278-zed-cline-agents-fallback/todo.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md b/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md index b907d46f9..b1302dfb0 100644 --- a/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md +++ b/docs/todos/2026-06-19-issue-278-zed-cline-agents-fallback/todo.md @@ -80,6 +80,9 @@ - Final verification review found two Medium process gaps: the task record omitted the repo-required full test gate, and the plan's final diff command did not include untracked task record contents. Both were valid and fixed in this record/plan update. - Final `semgrep scan --config p/default --error --metrics=off .` exited 0: 0 findings, 920 tracked files scanned, 545 rules run. - Final staged `gitleaks protect --staged --redact` exited 0 with no leaks found. +- After merging current `origin/main` into the issue branch, `corepack pnpm exec vitest run test/backup-scheduler.test.ts` exited 0 with 8 tests passed, and `corepack pnpm test` exited 0 with 207 test files and 2,827 tests passed. +- Post-merge `semgrep scan --config p/default --error --metrics=off .` exited 0: 0 findings, 924 tracked files scanned, 545 rules run. +- Post-merge `gitleaks dir . --redact` exited 0 with no leaks found in the current worktree. An extra full-history `gitleaks detect --source . --redact` scan found 14 historical leaks outside the PR diff; the staged PR scan and current worktree scan were clean. - Sprint Contract status: all acceptance criteria met. README documents Zed MCP under `context_servers`, Zed Agent project instruction fallback via `.clinerules` and `AGENTS.md`, current Zed skill directories, and avoids claiming the Cline MCP adapter installs rules. - Residual risk: Zed documentation is current as of 2026-06-19 and may evolve; this change uses "current Zed" wording and does not add behavior.