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

type, title, description, tags, timestamp

type	title	description	tags	timestamp
reference	Agent Docs and Edits	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.	agents docs markdown hashline edit-recovery	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):

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