[bug] ZCode user-scope rules dropped: pull deletes ~/.zcode/AGENTS.md though ZCode loads it as its user instruction file #1029

Note: This issue was drafted by an AI coding agent (ZCode) on behalf of the reporter, based on first-hand reproduction logs. Evidence below is verbatim from actual runs; please treat the tone/wording accordingly.

Summary

On Windows, teamai pull deletes the ZCode user-scope instruction file ~/.zcode/AGENTS.md, judging it a stale block "in files no tool loads them from". However, ZCode does load ~/.zcode/AGENTS.md as its user instruction file (official documented behavior). As a result, there is currently no working channel to deliver team claudemd rules to ZCode, while teamai doctor reports all-green:

• the claudemd block channel does not write ~/.zcode/AGENTS.md (pull prints Synced shared instructions (1 file(s)), but that one file only lands in e.g. ~/.codex/AGENTS.md);
• manually placing the marked block in ~/.zcode/AGENTS.md gets deleted by the next teamai pull;
• the hook channel cannot inject rules either: on Windows, ZCode hooks launch via a vbs wrapper whose command line ends with >nul 2>&1, discarding the hook's stdout (this is the fix(zcode): launch hooks via hidden wscript VBS — no console flash, bounded wait #596 launcher, so it is by design).

Environment

• teamai-cli: 0.27.0 (published 2026-10-09, installed via npm i -g teamai-cli@latest)
• OS: Windows 11 24H2 (10.0.26100), ZCode desktop
• team repo: user scope (~/.teamai), custom toolPaths snapshot copied from the 0.26.0 default table
• Relevant config in teamai.yaml:

  zcode:
    skills: '.zcode/skills'
    agents: '.zcode/agents'
    settings: '.zcode/cli/config.json'
    mcp: '.agents/mcp.json'
    claudemd: '.zcode/AGENTS.md'   # ← the channel that is expected to work but does not

Reproduction

1. Team repo has claudemd/harness-rules.md; teamai.yaml maps zcode.claudemd: '.zcode/AGENTS.md'.

2. teamai pull --force →

   ✔ [user] Synced 42 skills (all updated)
   ✔ [user] Synced shared instructions (1 file(s))
   

   ~/.zcode/AGENTS.md is never created. The "1 file" goes to ~/.codex/AGENTS.md only.

3. Manually create ~/.zcode/AGENTS.md containing the exact marked block copied from the delivered ~/.codex/AGENTS.md (delimited by <!-- [teamai:claudemd:start] --> / ...end] -->).

4. Run teamai doctor →

   ✖ No team instruction blocks are left in files no tool loads them from
     → Earlier teamai releases left team instruction blocks in C:\Users\<user>\.zcode\AGENTS.md,
       which can carry another member's selection. Run `teamai pull`.
   

5. Run teamai pull →

   ℹ [user] Removed teamai instruction blocks from C:\Users\<user>\.zcode\AGENTS.md:
     replacement instructions are ready
   

   The file is deleted. After that, doctor is fully green again — with no team rules reaching ZCode at all.

Why the premise is wrong

#946 (closed 2026-10-04) listed "ZCode 3.14.3 from its source" among the tools it verified, and its fix delivered user-scope rule blocks only to tools like Codex ($CODEX_HOME/AGENTS.md). But ZCode's official configuration docs define:

User instruction file: ~/.zcode/AGENTS.md. Applies as default instructions for every workspace.
Merge order: user ~/.zcode/AGENTS.md is injected first, then the workspace <repo>/AGENTS.md.

We verified ZCode actually injects this file into the model context at session start (standard user-scope instruction file behavior). So the doctor check "files no tool loads them from" contains a false positive for ~/.zcode/AGENTS.md, and the cleanup deletes a file ZCode does load.

Side note on the hook channel: the session-start dispatch for zcode logs team-rules ... (ok) every run, yet the hook's stdout is discarded by the vbs wrapper (>nul 2>&1), so even a non-empty rules payload could not reach the model through hooks either. This means for ZCode the only viable channel is the file ~/.zcode/AGENTS.md — which pull actively deletes.

Expected

• teamai pull writes the claudemd block to ~/.zcode/AGENTS.md when toolPaths.zcode.claudemd is configured (consistent with what the config comment and the [bug] Team rules miss most tools: each tool's own rules format, else a file only it reads, else a hook or extension in project scope #946 fix intended), or
• at minimum, the "no tool loads them from" check must not treat ~/.zcode/AGENTS.md as residue, and doctor should surface the delivery gap instead of reporting all-green.

Actual

• pull reports success ("Synced shared instructions") while ZCode receives nothing; a manually placed file is deleted on the next pull; doctor passes.

Suggested fix

Add ZCode to the instruction-delivery targets (user scope: ~/.zcode/AGENTS.md, already declared in the toolPaths default as claudemd), and align the residue-cleanup allowlist with the same target list so it cannot delete its own delivery destination.

Workaround currently in place

We disabled zcode.claudemd in our teamai.yaml and documented the gap in a comment, so pull no longer oscillates between "manually placed" and "deleted as residue". Happy to re-enable and re-test as soon as a fix lands.