serverAppConfigs/serverAppConfigs-docs/Agent/Agent Docs and Edits.md

---
type: reference
title: Agent Docs and Edits
description: Two self-inflicted damage classes — structurally broken markdown after parallel agent edits, and botched hashline PUT/CUT repairs — with the audit checks and recovery order for each.
tags: [agents, docs, markdown, hashline, edit-recovery]
timestamp: 2026-10-05T00:00:00-07:00
---

# Agent Docs and Edits

## Doc-structure audit (after parallel agent edits)

Use after one or more subagents have edited markdown docs (OKF/Obsidian
vault with `---` frontmatter), before committing. Link checkers and
completeness seams validate *references*, not *structure* — agents reliably
produce structurally broken markdown that still links cleanly.

Damage catalogue:

1. Banner/prose prepended **above** the opening `---` → the frontmatter is
   no longer frontmatter (title/tags/description become body text).
2. A rewrite **appended** instead of merged → duplicate headings and a stray
   second `---` mid-file.
3. Literal model artifacts in the body: `<|channel>}<tool_call|>...`,
   `+- `, `- - `.
4. Wrapped bullets re-emitted with a `- ` prefix on every physical line.
5. Line-range replacement that dropped a sentence tail → dangling fragment,
   often mid-parenthesis.

Checks (fast, run all):

```bash
head -3 <file>                          # must be `---` if the page has frontmatter
grep -c '^---$' <file>                  # exactly 2 (opener + closer)
grep -n '^## ' <file> | sort -t: -k2 | uniq -f1 -d   # duplicate sections
grep -rnE '^\+- |^- - |<\|' <files>     # artifacts
python3 scripts/check-vault-links.py <vault-dir>
./tests/run.sh                          # docs completeness seam etc.
```

Repair order (matters):

1. If the file was destroyed rather than edited: stash the agent version to
   `.AGENTTRASH/<YYYYMMDD-topic>/`, then `git checkout HEAD -- <file>` and
   re-apply only the intended changes by hand.
2. If it merely duplicated: **salvage unique content first** — cut the
   one-of-a-kind section, paste it into the copy you keep, THEN delete the
   duplicate ranges. Never delete first.
3. Re-add missing sentence tails (insert before the orphaned fragment),
   keeping list continuation lines indented.
4. Re-run all checks above.

Gotchas: agents can write AFTER they appear finished (job settles, file
changes) — re-verify structure after the last background job reports, not
before. Editing an agent's already-damaged file with fresh line numbers is
safe, but its snapshot tag changes on every edit — re-read before each
subsequent edit. `.AGENTTRASH/` is gitignored: trash is local-only, so
nothing moved there reaches the repo — that is intended (temporary hold, not
archive).

## Hashline edit recovery

Failure mode: multi-op edits resolve every `PUT N.=M:` / `CUT N.=M:` index
against the **original** file numbering, and the post-apply diff view
**elides lines** (it shows an anchor window, not the whole file). Two traps
follow:

1. A second edit call built from a diff-view snapshot uses line numbers from
   a *partial* view. Lines outside the window are invisible but still
   counted.
2. If the first apply was itself wrong, the file shifted. The diff view
   tells you the damage, but not the true offsets.

Result: the repair pastes fresh text **beside** stale text instead of over
it.

Procedure:

1. **Never carry line numbers across calls.** Re-read the target range for a
   fresh tag before every subsequent edit. A read is cheap; a duplicated
   paragraph costs a commit and a revert.
2. **One op per call when the previous apply was imperfect.** Fixed offsets
   are only trustworthy when every preceding apply landed exactly as
   specified.
3. **Re-read after every apply**, and verify the whole affected region — the
   diff view is a sample, not proof. Check the *boundaries*: the line before
   the edit and the line after it. Damage shows up as a repeated sentence
   straddling the seam.
4. **Repair by CUT, not by re-PUT.** Once you know the exact stale lines
   from a fresh read, delete them. Do not try to PUT a corrected superset
   over a range whose extent you are guessing at.
5. Verify with a content assertion, not a diff review: `grep -c` for the
   duplicated sentence, plus a syntax/compile check on any touched script.

Same rule for any imperative `edit` tool with an old/new match: the matched
text must be the **entire** text being replaced. Matching a bare fragment
inside a paragraph splices the replacement into the middle of the sentence
and silently corrupts the file. Re-read the file afterwards to confirm.

### Anchored in-page links

Renaming a Markdown heading breaks `[[#Old Heading]]` anchors. When a
section is retitled, grep for the old heading text and fix every anchor in
the same pass — doc link-checkers frequently do not validate `#fragment`
targets, so a green suite will not catch a dangling one.

## Related

- [[OMP Harness]] — the session context these repairs protect
- [[Command Center Dotfiles]] — the repo these edits commit to
- [[Testing Policy]] — the seams that catch broken vault structure