docs(bin): clarify fm-ensure-agents-md relocates content, never removes it

[pramendra]

Intent

Clarify bin/fm-ensure-agents-md.sh so its interface cannot be misread as data loss. The helper relocates a real CLAUDE.md into AGENTS.md: it moves every line, appends the canonical '## Maintaining this file' section, and replaces the original with the two-line @AGENTS.md pointer; nothing is removed. The task is to add a note to --help (and the header comment) stating that content is relocated rather than removed, and to surface the root-file side effects (AGENTS.md grows by the appended section, CLAUDE.md shrinks to the pointer) so a caller can anticipate a project CI gate that checks doc placement or a doc budget. Add a behavior test pinning the --help wording.

What Changed

• Added a help routine to bin/fm-ensure-agents-md.sh and expanded its header comment so --help and the script header now state that promotion relocates every CLAUDE.md line into AGENTS.md rather than removing content, and surfaces the side effects: AGENTS.md grows by the appended self-governance section while CLAUDE.md shrinks to the two-line pointer.
• Added a behavior test (test_help_states_relocation_not_removal) pinning the --help wording.
• Added Serena project configuration (.serena/project.yml and .serena/.gitignore).

Risk Assessment

✅ Low: The change is purely additive documentation and a help-wording behavior test with no functional logic changes, and it satisfies every required constraint in the authoritative intent.

Testing

Ran the targeted test suite (all 17 tests pass, including the new --help wording test), exercised --help directly to confirm it states content is relocated rather than removed and surfaces the AGENTS.md-grows/CLAUDE.md-shrinks side effects, and performed an end-to-end promotion showing a 3-line CLAUDE.md is fully relocated into AGENTS.md with the canonical section appended while CLAUDE.md shrinks to the two-line pointer; no failures or actionable findings.

Evidence: --help wording and end-to-end relocation transcript

Source: --help wording and end-to-end relocation transcript

usage: fm-ensure-agents-md.sh [repo-or-worktree-dir] ...its content is relocated, never removed: every line moves into AGENTS.md... Promotion appends the canonical "## Maintaining this file" section to AGENTS.md and replaces the real CLAUDE.md with the two-line pointer... Promotion run: 'promoted: moved CLAUDE.md to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer' -> AGENTS.md: 11 lines (3 original content lines + appended section), CLAUDE.md: 2 lines (pointer).

=== fm-ensure-agents-md.sh --help ===
usage: fm-ensure-agents-md.sh [repo-or-worktree-dir]

Ensure the worktree follows the agent-memory convention: AGENTS.md is the
real memory file and CLAUDE.md is a two-line @AGENTS.md pointer. When only a
real CLAUDE.md exists, its content is relocated, never removed: every line
moves into AGENTS.md and the original CLAUDE.md becomes the pointer.
Promotion appends the canonical "## Maintaining this file" section to AGENTS.md
and replaces the real CLAUDE.md with the two-line pointer; anticipate those
root-file changes before running this in a project whose CI gates check doc
placement or a doc budget.
Refuses to clobber distinct real files or wrong symlinks.

=== Promotion end-to-end (relocate, never remove) ===
--- BEFORE: CLAUDE.md (3 content lines + trailing newline) ---
# Alpha notes

- Run make test
- Deploy with kubectl
--- RUN: ./bin/fm-ensure-agents-md.sh <repo> ---
promoted: moved CLAUDE.md to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in /private/var/folders/y_/9gbx7zj559ddcnld9h975dph0000gn/T/tmp.Mg8sLVHcDz
--- AFTER: AGENTS.md (all 3 content lines preserved + appended section) ---
# Alpha notes

- Run make test
- Deploy with kubectl

## Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project.
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
Prefer rewriting or pruning existing entries over appending new ones.
When updating this file, preserve this bar for all agents and keep entries concise.
--- AFTER: CLAUDE.md (shrunk to the 2-line pointer) ---
<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
@AGENTS.md
--- line counts ---
AGENTS.md:       11 lines
CLAUDE.md:        2 lines

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-ensure-agents-md.test.sh (17 tests, incl. new test_help_states_relocation_not_removal, all pass)
• ./bin/fm-ensure-agents-md.sh --help (manual check of the relocation wording and side-effect disclosure)
• Manual end-to-end promotion: ran ./bin/fm-ensure-agents-md.sh against a repo with a 3-line CLAUDE.md, confirmed every line moved into AGENTS.md, the canonical section was appended, and CLAUDE.md became the 2-line pointer
• Regression check: base commit 505c819 bin/fm-ensure-agents-md.sh --help emitted only the one-line usage (missing relocation wording), confirming the new test fails before and passes after the change
• bash -n syntax check on bin/fm-ensure-agents-md.sh and tests/fm-ensure-agents-md.test.sh

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

_{Reviews (3): Last reviewed commit: "chore: drop Serena MCP auto-generated co..." | Re-trigger Greptile}