DevClaw still overwrites workspace-root AGENTS.md/HEARTBEAT.md/TOOLS.md on startup, despite conflicting history

[fujiwaranosai850]

Summary

lib/setup/workspace.ts in current upstream DevClaw still overwrites workspace-root AGENTS.md, HEARTBEAT.md, and TOOLS.md during startup/heartbeat via ensureDefaultFiles().

This appears inconsistent with part of the project's own issue/PR history, and it makes user-owned workspace bootstrap files effectively non-editable in practice.

Current behavior

In current upstream release and main, ensureDefaultFiles() contains behavior equivalent to:

• system instruction files are "always refreshed"
• system instruction files "always overwrite"
• backupAndWrite(path.join(workspacePath, "AGENTS.md"), AGENTS_MD_TEMPLATE)
• same for HEARTBEAT.md and TOOLS.md

The code comment also says ensureDefaultFiles() is called on every heartbeat startup.

Why this is a problem

For OpenClaw users, workspace-root bootstrap files look like user-owned context files.

But in DevClaw, AGENTS.md is documented as being written during setup and is in practice re-overwritten later as part of normal runtime startup.

That means:

• user edits to root AGENTS.md can be silently clobbered
• root workspace guidance becomes unreliable
• plugin-specific orchestration policy can unexpectedly take over global workspace behavior
• this is difficult to reason about because the user-facing docs do not clearly say that these files may continue to be overwritten after setup

Conflicting upstream history

I found upstream items that point in different directions:

Says overwrites should stop

• Issue Stop overwriting user config: separate defaults layer with package fallbacks #463: "Stop overwriting user config: separate defaults layer with package fallbacks"
  • checklist explicitly includes removing AGENTS.md/HEARTBEAT.md/IDENTITY.md/TOOLS.md overwrites
• PR Stop overwriting user config: separate defaults layer with package fallbacks #467
  • says: "Removed workspace doc overwrites (AGENTS.md, etc.)"

Says some overwrites should remain

• Issue Stop overwriting user config on restart — implement write-once defaults with version tracking #464
  • says AGENTS.md, HEARTBEAT.md, TOOLS.md remain always-overwrite system instructions
• PR feat: write-once defaults with version tracking and config tools #468
  • says the same in its summary/tests

Current shipped behavior

• current release still overwrites AGENTS.md, HEARTBEAT.md, TOOLS.md

So from the outside, this looks unresolved or contradictory.

Suggested fix

I think DevClaw should stop overwriting workspace-root AGENTS.md, HEARTBEAT.md, and TOOLS.md during normal startup/heartbeat.

Recommended behavior:

• normal startup: create these files only if missing
• explicit reset/eject commands: write/overwrite defaults when user asks for it
• keep plugin-specific deeper policy under devclaw/ or other plugin-owned paths instead of taking ownership of workspace-root files

Repro / observed effect

On a live setup, repeated reads of workspace-root AGENTS.md showed it flipping between different first lines because another runtime path was rewriting it.

The write path traced back to:

• lib/setup/workspace.ts
• ensureDefaultFiles()
• backupAndWrite(... "AGENTS.md" ...)

Request

Can this behavior be clarified and, ideally, changed so workspace-root bootstrap files are user-owned after initial setup unless the user explicitly resets them?

[fujiwaranosai850]

Related follow-on bug record: #536

A prepared export package for the root-doc normalization family is available here:

• main...yaqub0r:pr/159-root-doc-normalization-e2e

That package includes the tagged-block bootstrap ownership prerequisite plus the duplicate-normalization fix.